Skip to content

API reference

Base URL: https://api.treechat.com/api/apps/v1

  • Send Authorization: Bearer ACCESS_TOKEN on every request.
  • Request bodies are JSON (Content-Type: application/json). Responses are JSON with Cache-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).
MethodPathScopeDoes
GET/meaccount:readThe connected member
POST/poststreechat:writeStart a thread, reply, or reply in a branch
GET/operations/{id}treechat:writeStatus of a post that returned 202
POST/uploadsuploads:writeGet an upload URL for a file to attach
GET/threadstreechat:readList threads
GET/threads/{id}treechat:readOne thread with its posts
GET/posts/{id}treechat:readOne post

GET /me

Terminal window
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:

FieldTypeUse
contentstringThe text. Plain text; links are detected.
delta_jsonobjectRich text as a Quill Delta, instead of content.
filesstring[]signed_id values from POST /uploads.
thread_idstringReply in this thread.
reply_to_post_idstringWith thread_id: reply to this post in it.
branch_from_post_idstringReply in this post’s branch, starting the branch if it has none.
publicbooleanNew threads only. true makes the thread public. Default: private.
privatebooleanNew threads only. The opposite of public; send one or the other.
space_idstringNew 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 sendResult
No thread_id or branch_from_post_idA new thread
thread_idA reply in that thread
thread_id + reply_to_post_idA reply to that post
branch_from_post_idA 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:

Terminal window
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:

Terminal window
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.

Terminal window
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:

  1. POST /uploads with the file’s details.
  2. PUT the raw bytes to the returned upload.url, sending exactly the returned upload.headers. Don’t send your access token there.
  3. Put the returned signed_id in a post’s files.
FieldTypeValue
filenamestringFor example episode-1.png
content_typestringMIME type, for example image/png, video/mp4, audio/mpeg
byte_sizeintegerExact size in bytes
checksumstringBase64 of the file’s MD5 digest
Terminal window
FILE=episode-1.png
CHECKSUM=$(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": "…" }
}
}
Terminal window
curl -X PUT "UPLOAD_URL" -H "Content-Type: image/png" -H "Content-MD5: CHECKSUM" --data-binary @episode-1.png

GET /threads

Lists threads. Without parameters: threads the connected member started, newest first.

ParameterUse
userA username (with or without @), a user ID, or me: threads that person started that the member can see.
publictrue: the public feed instead.
orderWith public=true: time (default), upvalue or upvalueTrending.
beforeWith public=true and order=time: the next_cursor from the previous page.
limit1–100 for the public time feed (default 20); also used for member listings.
pagePage number for member listings and ranked public orders.
space_idLimit to one community.
Terminal window
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:

ListingpaginationNext page
Member threads (user or no parameters)page, has_morepage + 1
Public, order=timelimit, next_cursor, has_morebefore=next_cursor
Public, ranked orderspage, limit, next_page, has_morepage=next_page

Each thread object uses Treechat’s existing thread JSON (see below).

GET /threads/{id}

Terminal window
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}

Terminal window
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 JSONMeans
questA thread
answerA post
child_questsBranches that grow out of a post
delta_jsonA post’s rich text as a Quill Delta

Treat unknown fields as optional; new ones may be added.