# API reference

> Every App Connect REST endpoint with its permission, fields, responses and a curl example.

Source: https://docs.treechat.com/developers/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](https://docs.treechat.com/developers/limits-and-errors/#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

```bash
curl https://api.treechat.com/api/apps/v1/me -H "Authorization: Bearer ACCESS_TOKEN"
```

`200`:

```json
{ "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](https://docs.treechat.com/developers/limits-and-errors/#retries-and-idempotency)).

**Body fields:**

| Field                 | Type     | Use                                                                                  |
| --------------------- | -------- | ------------------------------------------------------------------------------------ |
| `content`             | string   | The text. Plain text; links are detected.                                            |
| `delta_json`          | object   | Rich text as a [Quill Delta](https://quilljs.com/docs/delta/), instead of `content`. |
| `files`               | string[] | `signed_id` values from [`POST /uploads`](#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:**

```bash
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:**

```bash
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):

```json
{
    "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.

```bash
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`.

| 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                               |

```bash
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`:

```json
{
    "signed_id": "eyJfcmFpbHMiOnsi…",
    "upload": {
        "url": "https://storage.example/…",
        "headers": { "Content-Type": "image/png", "Content-MD5": "…" }
    }
}
```

```bash
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.

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

```bash
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}

```bash
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}

```bash
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.
