Treechat

Connect with Treechat

Add a “Connect with Treechat” button to your app. People sign in on Treechat, approve what your app may do, and your app can then post, reply, upload and read for them. Nobody shares a password with you.

Sign in to register an app

1. Register

2. Send people to sign in

Standard OAuth 2.0 authorization code flow with PKCE (S256 required). Redirect the browser to:

https://api.treechat.com/mcp/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/treechat/callback
  &scope=public:write%20channels%20uploads:write%20treechat:read
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
  &resource=https://api.treechat.com/mcp

Treechat shows the person your app’s name, homepage and your username.

3. Trade the code for tokens

curl -X POST https://api.treechat.com/mcp/oauth/token \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_REDIRECT \
  -d redirect_uri=https://yourapp.com/auth/treechat/callback \
  -d code_verifier=YOUR_VERIFIER \
  -d resource=https://api.treechat.com/mcp

Access tokens last 15 minutes. Use the refresh token (grant_type=refresh_token) to get a new pair; each refresh token works once. A connection unused for 30 days has to be approved again.

4. Post, upload and read

Call the REST API at https://api.treechat.com/api/apps/v1 with the access token. Requests and responses are JSON.

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 up","files":["SIGNED_ID"]}'

A new post returns 201 with post_id and thread_id. Send an Idempotency-Key with every post and reuse it if you retry, so nothing is posted twice. If you get 202, the post is still being saved: check GET /api/apps/v1/operations/OPERATION_ID and don’t retry with a new key.

RequestPermissionWhat it does
POST /posts with public: truepublic:writeStarts a new public thread. Fields: content, files (upload signed_ids), and space_id.
POST /posts with channel_idchannelsStarts a new thread in a channel the person picked for your app (public or private).
POST /posts with thread_idpublic:write or channelsReplies in that thread: a public thread needs public:write, a channel thread needs that channel picked. Add reply_to_post_id to answer a specific post.
POST /posts with branch_from_post_idpublic:write or channelsReplies in that post’s branch (the thread hanging off it), and starts the branch if the post doesn’t have one yet. Same rule as replies.
POST /uploadsuploads:writeSend filename, content_type, byte_size and checksum (base64 MD5). PUT the bytes to the returned upload.url with exactly the returned upload.headers (not your access token), then post with the signed_id.
GET /threads/:id, GET /posts/:idtreechat:readA thread with its posts, or one post, if the person can see it.
GET /threadstreechat:readThreads for user (a username), or the public feed with public=true. Pages with page, limit and before.
GET /meaccount:readThe connected person’s ID and username.

Errors look like {"error":{"code":"…","message":"…"}}. A 401 means the token expired or was revoked: refresh it. A 403 with app_suspended means Treechat suspended your app. Posts your app makes show “via your app name”. Apps post only in public threads or in channels the person picked: private threads and DMs get 403 forbidden. Apps can’t spend the person’s money.

MCP clients can use the same token at https://api.treechat.com/mcp instead.

5. Get new posts pushed to you (webhooks)

Instead of polling, ask Treechat to call your server when someone posts in channels the person picked for your app.

curl -X POST https://api.treechat.com/api/apps/v1/webhooks \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/treechat","team_ids":["STREAM_ID"],"replies_only":false}'

The response holds a secret, shown only once. Treechat then POSTs a post.created event for every new post there that the connected person can read, with the post’s Markdown, author, thread, parent and link. Posts your app made are not sent back to you.

Check every call before trusting it: X-Treechat-Signature is sha256= followed by the hex HMAC-SHA256 of X-Treechat-Timestamp, a dot and the raw body, keyed with your secret. Reject timestamps more than 5 minutes old, and skip a X-Treechat-Delivery-Id you have already handled. Answer with any 2xx; Treechat retries other answers for about a day, stops after a 410, and switches a webhook off after 20 failures in a row (turn it back on with PATCH /webhooks/:id and "enabled":true).

If your receiver refuses calls without an Authorization header, pass "authorization":"Bearer YOUR_RECEIVER_KEY" when you create the webhook (or later with PATCH; null removes it). Treechat sends that value as the Authorization header on every call, next to the signature headers. It is stored encrypted and never returned: reads show only has_authorization.

Also: GET /webhooks, PATCH and DELETE /webhooks/:id, POST /webhooks/:id/rotate_secret, and POST /webhooks/:id/ping to send a test event. All need channels, and a webhook can list only channels the person picked (on the consent page or later on Connected apps). Up to 10 webhooks per person. Disconnecting your app deletes its webhooks.

Limits

Full guide and reference: docs.treechat.com/developers. For code generators and AI agents: OpenAPI description and llms.txt.

Discovery metadata: https://api.treechat.com/.well-known/oauth-authorization-server