# Connect your app to Treechat

App Connect lets people connect your app to their Treechat account. They sign in on Treechat and approve what your app may do. Your app then posts, replies, uploads and reads for them through a JSON REST API. Nobody shares a password with you.

REST API base: `https://api.treechat.com/api/apps/v1`

- Register and manage apps: https://api.treechat.com/mcp/oauth/apps
- Step-by-step guide with every field: https://api.treechat.com/developers/apps
- Full docs: https://docs.treechat.com/developers/overview/
- OpenAPI 3.1: https://api.treechat.com/api/apps/v1/openapi.json
- Docs index for agents: https://docs.treechat.com/llms.txt
- OAuth discovery: https://api.treechat.com/.well-known/oauth-authorization-server

## Connect in 4 steps

### 1. Register your app

Sign in at https://api.treechat.com/mcp/oauth/apps and give your app a name, a homepage and the exact redirect URIs you'll use (https, or `http://localhost` while you build). Pick only the permissions you need. You get a client ID and a client secret. The secret is shown once; keep it on your server. The app works for anyone as soon as it is registered.

### 2. Send people to sign in

Authorization code flow with PKCE (S256 is 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, and lets them pick which channels your app may use.

### 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. Get a new pair with `grant_type=refresh_token`; each refresh token works once, so save the new one every time.

### 4. Post, upload and read

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

`201` returns `post_id` and `thread_id`.

- New public thread: `POST /posts` with `"public": true` (needs `public:write`).
- New thread in a channel: `POST /posts` with `channel_id` (needs `channels` and that channel picked by the person).
- Reply: `POST /posts` with `thread_id`, plus `reply_to_post_id` for a specific post.
- Reply in a post's branch: `POST /posts` with `branch_from_post_id`.
- Upload: `POST /uploads` with `filename`, `content_type`, `byte_size` and `checksum` (base64 MD5), PUT the bytes to `upload.url` with exactly `upload.headers`, then post with the `signed_id`.
- Read: `GET /threads/:id`, `GET /posts/:id`, `GET /threads` (`user=USERNAME` or `public=true`), `GET /me`.

## Permissions

- `public:write`: start public threads and reply in public threads.
- `channels`: post in, and get webhooks from, the channels the person picked for your app. They can change the list later on Connected apps.
- `uploads:write`: upload images, audio and video to attach to posts.
- `treechat:read`: read threads and posts the person can see, and list a user's threads or the public feed.
- `account:read`: read the connected person's ID and username (`GET /me`).

Apps can't post in private threads or DMs, create channels, invite people or spend the person's money. `treechat:write` is not available to third-party apps. Posts show "via <your app name>".

## What trips people up

- Send an `Idempotency-Key` header with every post and reuse it when you retry, so nothing is posted twice.
- A `202` means the post is still being saved. Check `GET /api/apps/v1/operations/OPERATION_ID`; don't retry with a new key.
- A new thread needs `"public": true` or a `channel_id`. Without either it would be private, and apps can't post privately, so the request is refused.
- Access tokens last 15 minutes. A `401` means refresh. Each refresh token works once. A connection unused for 30 days has to be approved again.
- Uploads: PUT the bytes to the returned `upload.url` with exactly the returned `upload.headers`. Don't add your access token.
- Errors look like `{"error":{"code":"…","message":"…"}}`. A `403` with `app_suspended` means Treechat suspended your app.

## Limits

- Posts: 30 a minute per connected person, and 60 an hour per person across all apps.
- Requests: 300 a minute per access token.
- Uploads: up to 2 GB per file and 10 GB a day per person.
- People see and remove the apps they connected at https://api.treechat.com/mcp/oauth/connections.

## Webhooks

`POST /api/apps/v1/webhooks` (needs `channels`) asks Treechat to send a signed `post.created` call for every new post in the channels the person picked, instead of polling. Up to 10 webhooks per person. Signature check, retries and the other webhook calls: https://api.treechat.com/developers/apps

## For AI agents

Prompt for a coding agent:

1. Read https://treechat.com/apps.md and https://docs.treechat.com/llms.txt.
2. Use the OpenAPI file https://api.treechat.com/api/apps/v1/openapi.json for request and response shapes.
3. OAuth 2.0 authorization code + PKCE (S256) against api.treechat.com, with `resource=https://api.treechat.com/mcp`. Keep the client secret on the server. I will register the app and give you the client ID.
4. Store the refresh token and replace it after every refresh.
5. Send an Idempotency-Key on every post and `"public": true` (or a `channel_id`) on new threads.

Facts:

- REST API base: `https://api.treechat.com/api/apps/v1`. OpenAPI 3.1: https://api.treechat.com/api/apps/v1/openapi.json
- OAuth discovery: https://api.treechat.com/.well-known/oauth-authorization-server. Authorize at `/mcp/oauth/authorize`, tokens at `/mcp/oauth/token`. Send `resource=https://api.treechat.com/mcp` on both.
- Scopes for registered apps: `public:write`, `channels`, `uploads:write`, `treechat:read`, `account:read`.
- In read responses a thread is called "quest" and a post "answer".
- MCP clients can use the same token at `https://api.treechat.com/mcp`. To connect your own assistant instead of connecting an app, see https://treechat.com/mcp.

More: https://treechat.com/mcp · https://treechat.com/cli · https://docs.treechat.com
