API reference
Base URL: https://api.treechat.com/api/apps/v1
- Send
Authorization: Bearer ACCESS_TOKENon every request. - Request bodies are JSON (
Content-Type: application/json). Responses are JSON withCache-Control: no-store. - IDs are UUID strings.
- Errors follow the shared error format.
- A machine-readable copy of this page is at
https://api.treechat.com/api/apps/v1/openapi.json(OpenAPI 3.1).
| Method | Path | Scope | Does |
|---|---|---|---|
GET | /me | account:read | The connected member |
POST | /posts | treechat:write | Start a thread, reply, or reply in a branch |
GET | /operations/{id} | treechat:write | Status of a post that returned 202 |
POST | /uploads | uploads:write | Get an upload URL for a file to attach |
GET | /threads | treechat:read | List threads |
GET | /threads/{id} | treechat:read | One thread with its posts |
GET | /posts/{id} | treechat:read | One post |
GET /me
curl https://api.treechat.com/api/apps/v1/me -H "Authorization: Bearer ACCESS_TOKEN"200:
{ "id": "af899143-90bc-4793-ba06-7f4655a0ef39", "username": "clip_fan", "space_id": "…" }POST /posts
Makes one post. Which kind depends on the fields you send.
Headers: Idempotency-Key (required; see retries).
Body fields:
| Field | Type | Use |
|---|---|---|
content | string | The text. Plain text; links are detected. |
delta_json | object | Rich text as a Quill Delta, instead of content. |
files | string[] | signed_id values from POST /uploads. |
thread_id | string | Reply in this thread. |
reply_to_post_id | string | With thread_id: reply to this post in it. |
branch_from_post_id | string | Reply in this post’s branch, starting the branch if it has none. |
public | boolean | New threads only. true makes the thread public. Default: private. |
private | boolean | New threads only. The opposite of public; send one or the other. |
space_id | string | New threads only. The community to post in; defaults to the member’s. |
At least one of content, delta_json or files is required. Unknown fields are refused with 422.
| You send | Result |
|---|---|
No thread_id or branch_from_post_id | A new thread |
thread_id | A reply in that thread |
thread_id + reply_to_post_id | A reply to that post |
branch_from_post_id | A reply in that post’s branch |
branch_from_post_id can’t be combined with thread_id or reply_to_post_id. public, private and space_id are only for new threads.
Start a public thread with an image:
curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1" \ -d '{"content":"Episode 1 is live","files":["SIGNED_ID"],"public":true}'Start a branch off a post:
curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1-bts" \ -d '{"content":"Behind the scenes","branch_from_post_id":"POST_ID"}'Response (201 posted, 202 not confirmed yet):
{ "operation_id": "5f0c…", "state": "completed", "thread_id": "72db5fc4-36bb-5c1e-b13e-9e68ec760d35", "post_id": "1b9e…"}For a new thread, thread_id is the new thread and post_id its first post. For a reply or branch reply, thread_id is the thread (or branch) it landed in.
GET /operations/{id}
Checks a post that came back 202. Only your app’s operations for this member are visible.
curl https://api.treechat.com/api/apps/v1/operations/OPERATION_ID -H "Authorization: Bearer ACCESS_TOKEN"Returns the same shape as POST /posts: 200 when completed, 202 while pending, or the rejection error.
POST /uploads
Uploading a file takes three steps:
POST /uploadswith the file’s details.PUTthe raw bytes to the returnedupload.url, sending exactly the returnedupload.headers. Don’t send your access token there.- Put the returned
signed_idin a post’sfiles.
| Field | Type | Value |
|---|---|---|
filename | string | For example episode-1.png |
content_type | string | MIME type, for example image/png, video/mp4, audio/mpeg |
byte_size | integer | Exact size in bytes |
checksum | string | Base64 of the file’s MD5 digest |
FILE=episode-1.pngCHECKSUM=$(openssl dgst -md5 -binary "$FILE" | openssl base64)SIZE=$(wc -c < "$FILE" | tr -d ' ')
curl -X POST https://api.treechat.com/api/apps/v1/uploads \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"filename\":\"$FILE\",\"content_type\":\"image/png\",\"byte_size\":$SIZE,\"checksum\":\"$CHECKSUM\"}"201:
{ "signed_id": "eyJfcmFpbHMiOnsi…", "upload": { "url": "https://storage.example/…", "headers": { "Content-Type": "image/png", "Content-MD5": "…" } }}curl -X PUT "UPLOAD_URL" -H "Content-Type: image/png" -H "Content-MD5: CHECKSUM" --data-binary @episode-1.pngGET /threads
Lists threads. Without parameters: threads the connected member started, newest first.
| Parameter | Use |
|---|---|
user | A username (with or without @), a user ID, or me: threads that person started that the member can see. |
public | true: the public feed instead. |
order | With public=true: time (default), upvalue or upvalueTrending. |
before | With public=true and order=time: the next_cursor from the previous page. |
limit | 1–100 for the public time feed (default 20); also used for member listings. |
page | Page number for member listings and ranked public orders. |
space_id | Limit to one community. |
curl "https://api.treechat.com/api/apps/v1/threads?public=true&limit=10" -H "Authorization: Bearer ACCESS_TOKEN"Every listing returns {"threads": [...], "pagination": {...}}. What’s in pagination depends on how you page:
| Listing | pagination | Next page |
|---|---|---|
Member threads (user or no parameters) | page, has_more | page + 1 |
Public, order=time | limit, next_cursor, has_more | before=next_cursor |
| Public, ranked orders | page, limit, next_page, has_more | page=next_page |
Each thread object uses Treechat’s existing thread JSON (see below).
GET /threads/{id}
curl https://api.treechat.com/api/apps/v1/threads/THREAD_ID -H "Authorization: Bearer ACCESS_TOKEN"200 returns {"quest": {...}}: the thread, with its posts under answers. A thread the member can’t see returns 404.
GET /posts/{id}
curl https://api.treechat.com/api/apps/v1/posts/POST_ID -H "Authorization: Bearer ACCESS_TOKEN"200 returns {"answer": {...}}: the post, with quest_id (its thread) and child_quests (branches growing from it).
Thread and post JSON
Read responses reuse the JSON Treechat’s own apps use, so they’re larger than the write responses and use older names:
| In the JSON | Means |
|---|---|
quest | A thread |
answer | A post |
child_quests | Branches that grow out of a post |
delta_json | A post’s rich text as a Quill Delta |
Treat unknown fields as optional; new ones may be added.