Rocoto API

Version 1 · read-only · JSON

Build apps, widgets and sites that show Rocoto's content to people. The API gives you the posts, comments, pathways and profiles that the key's owner could see on the site, as plain JSON.

Powered by Rocoto - https://www.rocoto.space

Quick start

1. Log in, then open Settings → Developer API and make a key. It looks like rk_... and is shown once, so copy it right away.
2. Send it with every request, in the Authorization header.

curl -H "Authorization: Bearer rk_YOUR_KEY" \
     "https://www.rocoto.space/api/v1/posts?limit=5"

Using a key

• A key acts as you, read-only: it can see exactly what you can see on Rocoto, nothing more. People you blocked (or who blocked you), locked accounts, other people's private or archived posts and friends-only profile details stay hidden.
• Keep it secret, like a password. Do not put it in code that other people can read. If it leaks, revoke it in Settings and make a new one. You can have up to 5 keys, and a key stops working when you revoke it or your account is locked.
• You can send it as Authorization: Bearer rk_... or as X-API-Key: rk_.... Keys in the address (?key=...) are not accepted, because addresses end up in logs.
• Any website may call the API from a browser (CORS is open), but remember that a key placed in a web page can be read by everybody who opens it.

Limits

Each key may make 30 requests per minute and has a daily share of 1,000 requests and 2,000 items (every post, comment, pathway or profile in an answer is one item). The day ends at midnight UTC. Over the per-minute limit you get 429 with rate_limited: wait a little and try again. Over the daily share you get 429 with quota_exceeded until tomorrow, and a key that keeps asking is switched off. Every answer says what is left in X-Rocoto-Quota-Items-Remaining and X-Rocoto-Quota-Requests-Remaining. Lists give at most 50 items per request.

Endpoints

All paths start with https://www.rocoto.space/api/v1. Every endpoint except the index needs a key.

Paging

Lists answer with {"data": [...], "next_before": 123}. Pass that number back as before to get the next, older page when a person scrolls on; when it is null there are no more. Paging counts against your daily share, so do not page through everything. Comments use next_after and after in the same way, pathways use next_offset and offset.

Example answer

GET /api/v1/posts?limit=1

{
  "data": [{
    "id": 482,
    "url": "https://www.rocoto.space/post/482",
    "title": null,
    "content": "Spring planting calendar, free to print.",
    "pathway": "Gardening",
    "pathway_url": "https://www.rocoto.space/pathway/Gardening",
    "author": {
      "username": "Maya",
      "profile_url": "https://www.rocoto.space/profile/Maya",
      "profile_pic": "https://www.rocoto.space/static/media/profile/Maya/pic/1a2b3c.png",
      "badges": []
    },
    "created_at": "2026-10-06T12:34:56+00:00",
    "edited_at": null,
    "likes": 12,
    "comments": 3,
    "pinned": false,
    "attachment": {"type": "pdf", "url": "https://www.rocoto.space/static/media/post/482/9f8e7d.pdf", "name": "Spring planting calendar.pdf", "size": 183422},
    "youtube_mode": "video"
  }],
  "next_before": 481
}

Attachment type is one of image, audio, video, pdf or file. Dates are ISO 8601 in UTC. Pictures and files are normal web addresses you can show or download.

Code examples

Python

import requests

API = "https://www.rocoto.space/api/v1"
headers = {"Authorization": "Bearer rk_YOUR_KEY", "User-Agent": "MyApp/1.0 (+https://example.com)"}

# Show the 10 newest posts of a pathway when a person opens that screen of your app
reply = requests.get(f"{API}/posts", headers=headers, params={"pathway": "Main", "limit": 10})
reply.raise_for_status()
for post in reply.json()["data"]:
    print(post["author"]["username"], post["content"][:60])

JavaScript

const reply = await fetch("https://www.rocoto.space/api/v1/pathways/Main", {
  headers: { Authorization: "Bearer rk_YOUR_KEY" },   // a browser sends its own User-Agent
});
if (!reply.ok) throw new Error((await reply.json()).error.message);
const { data } = await reply.json();
console.log(data.name, data.members, "members");

Errors

Errors have a matching HTTP status and a JSON body: {"error": {"code": "not_found", "message": "There is no such post."}}

Version 2: apps that act for a person

Version 2 lets an app (a phone app, a desktop client) read the feed and, if the person allows it, post, comment, like and report as that person. The person signs in on rocoto.space and approves the app; your app never sees their password. Version 1 and personal keys keep working as before.

1. Register your app in Settings > Developer apps: a name, the exact return addresses (https://..., http://127.0.0.1:port/... or your own scheme such as myapp://oauth). You get a client_id. A new app is in development mode: up to 25 people, and only you can give it permission to post.

2. Send the person to https://www.rocoto.space/oauth/authorize (in a browser or web view) with response_type=code, client_id, redirect_uri, scope (space-separated), a random state, and PKCE: code_challenge = base64url(SHA-256(verifier)) with code_challenge_method=S256. After they press Allow you get ?code=...&state=... at your return address.

3. Swap the code for tokens: POST https://www.rocoto.space/oauth/token (form fields) with grant_type=authorization_code, code, redirect_uri, client_id, code_verifier. The answer has an access_token (ra_..., 30 minutes) and a refresh_token (rr_...). When the access token expires, send grant_type=refresh_token, refresh_token, client_id and store the new pair: every refresh token works once, and showing an old one again cancels the whole chain. POST /oauth/revoke with token and client_id signs out.

4. Call the API with Authorization: Bearer ra_... and a User-Agent that names your app. Everything is under /api/v2, answers are JSON (plain text, never HTML), lists use cursors and return at most 50 items. What the person cannot see answers 404, like something that does not exist.

Limits per person and app: 600 requests an hour, 20 new posts, 100 comments and 20 reports a day, 300 likes an hour, 2,000 items returned a day while the app is in development (higher once it is reviewed). Posts and comments made through an app show via its name. People can remove an app any time in Settings > Connected apps, and apps that break the rules are switched off.

Please be kind

• The Terms of Use and Privacy Policy also apply to what you build. The ban on bots and scrapers applies to everything you build.
• Credit Rocoto and link to https://www.rocoto.space as described above, and link back to the post (url) when you show one. The authors own what they post.
• Cache what you can and respect the limits. Keys that overload the site or break these rules are switched off.
• The API is read-only for now. Version 1 will keep working as it is described here; new fields may be added, so ignore fields you do not know.
• Questions or ideas? Write to us.