> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser API

> The public thesis API on id.cabalspy.xyz for client-side apps: every call carries your instance's public client_id; public reads, writes with the user's access token (scope thesis) and a public live websocket per token.

The thesis widget runs on a small public API on id.cabalspy.xyz. Client-side apps can use it directly, without a backend and without an API key. Every call carries your instance's public client\_id, see [Client ID](#client-id):

* **Reading** is public: no user token is needed. Browser calls are answered from your instance's allowed origins (CORS).
* **Writing** uses the signed-in user's CabalSpy ID access token as `Authorization: Bearer <token>`. The token must carry the scope `thesis`, so request it at sign-in, for example with `data-scope="openid profile thesis"` on the [login button](https://docs.cabalspy.xyz/cabalspy-id/login-button.md).

For server-to-server writing with your API key, use the [Data API](https://docs.cabalspy.xyz/cabalspy-id/theses-post.md) instead.

## Client ID

Every call of the browser API carries your instance's **public client\_id** (the Instance ID, `csid_...`). This applies to every read and write, reactions, reports, `/me/notifications`, the session exchange and pickup the widget uses, and the [websocket](#live-websocket). Send it as a header or as a query parameter:

```text theme={null}
X-CSID-Client-Id: csid_...
https://id.cabalspy.xyz/thesis/v1/tokens/solana/TOKEN_MINT?client_id=csid_...
```

* **Where to find it:** in the [API Dashboard](https://apidashboard.cabalspy.xyz) under **CabalSpy ID**, **Instances**, shown next to the API key.
* **It is public, not a secret.** The client\_id is not the API key. It is bound to the same dashboard account and plan, and is safe to ship in browser code.
* **Allowed origins:** browser calls are only answered from your instance's sites: the registered allowed origins, the origins of your redirect URIs and your verified domain including its subdomains (https). Instances that are not in live mode also accept `http://localhost:*` and `http://127.0.0.1:*`.
* **Servers:** calls without an `Origin` or `Referer` header, for example from your backend, only need a valid client\_id.
* If you send the client\_id both as header and as query parameter, they must match.

> [!WARNING]
>
> Never use your secret API key in a browser. For server-side data access use the [Data API](https://docs.cabalspy.xyz/cabalspy-id/data-api.md) on api-id.cabalspy.xyz with your API key, the same key as for the main CabalSpy API.

The [playground](https://id.cabalspy.xyz/try/thesis) and the public profile pages keep working as before, and the OpenID Connect discovery document and JWKS stay public.

## Base URL

```text theme={null}
https://id.cabalspy.xyz/thesis/v1
```

## Endpoints

Path parameters: `{chain}` is one of solana, bnb, base, eth, rh, `{mint}` the token address, `{id}` a thesis or reply id.

| Method | Path | Auth | Description |
| - | - | - | - |
| GET | `/tokens/{chain}/{mint}?sort=new\|top&stance=&limit=&cursor=` | – | Theses of a token. The response also carries `token` and `summary`. |
| GET | `/tokens/{chain}/{mint}/summary` | – | Counts and token info. |
| GET | `/tokens/{chain}/{mint}/me` | Bearer | Eligibility of the signed-in user plus their `user` (csid\_id, username, name, image\_url) and `notices` (unread, latest, url). |
| POST | `/tokens/{chain}/{mint}` | Bearer | Post a thesis: `{"body": "...", "stance": "bull"}`. Holders only. |
| GET | `/items/{id}` | – | One thesis or reply. |
| GET | `/items/{id}/replies?limit=&cursor=` | – | Replies, oldest first. |
| POST | `/items/{id}/replies` | Bearer | Reply: `{"body": "..."}`. |
| POST | `/items/{id}/reactions` | Bearer | React: `{"emoji": "like", "on": true}`. |
| POST | `/items/{id}/report` | Bearer | Report: `{"reason": "spam", "note": "..."}`. |
| DELETE | `/items/{id}` | Bearer | Delete your own post. |
| GET | `/users/{csid_id}?limit=&cursor=` | – | Theses of one user. |
| GET | `/me/notifications` | Bearer | The user's moderation notifications, see [Moderation](https://docs.cabalspy.xyz/cabalspy-id/theses-moderation.md#browser-api). |
| POST | `/me/notifications/read` | Bearer | Mark all notifications as read. |
| POST | `/me/notifications/{id}/appeal` | Bearer | Appeal a decision: `{"message": "..."}`. |

The theses list, the summary and the websocket show theses of all platforms. Add `scope=instance&client_id=csid_...` to show only the theses written on that instance, see [Reach](https://docs.cabalspy.xyz/cabalspy-id/theses.md#reach).

With a Bearer token on read requests, `my_reactions` and `is_mine` are filled for the signed-in user. Thesis objects are the same as in the [Data API](https://docs.cabalspy.xyz/cabalspy-id/theses-list.md#response).

```javascript theme={null}
const API = "https://id.cabalspy.xyz/thesis/v1";
const CLIENT_ID = "csid_..."; // your instance's public client_id

// read, no user token needed
const list = await (await fetch(`${API}/tokens/solana/${mint}?sort=top`, {
  headers: { "X-CSID-Client-Id": CLIENT_ID },
})).json();
console.log(list.summary, list.data);

// write with the access token from the login button (scope thesis)
const res = await fetch(`${API}/tokens/solana/${mint}`, {
  method: "POST",
  headers: {
    "X-CSID-Client-Id": CLIENT_ID,
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Strong community, still early.", stance: "bull" }),
});
const out = await res.json();
if (!out.success) alert(out.error.message);
```

## Responses

Success: `{"success": true, "data": ...}`, plus `pagination` (limit, has\_more, next\_cursor) on lists. Errors: `{"success": false, "error": {"code": "...", "message": "...", "docs": "..."}}`, where `docs` links to the code on the [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) page. The messages are written for end users.

Access tokens live 15 minutes. When a write returns `invalid_token`, refresh the token or let the user sign in again.

| Status | Code | Meaning |
| - | - | - |
| 401 | [client\_id\_required](https://docs.cabalspy.xyz/cabalspy-id/errors.md#client_id_required) | No client\_id was sent. |
| 401 | [invalid\_client](https://docs.cabalspy.xyz/cabalspy-id/errors.md#invalid_client) | Unknown, suspended or deleted instance, or header and query client\_id differ. |
| 403 | [origin\_not\_allowed](https://docs.cabalspy.xyz/cabalspy-id/errors.md#origin_not_allowed) | The page's origin is not one of your instance's allowed origins. |
| 401 | sign\_in\_required | No Bearer token was sent. |
| 401 | invalid\_token | Token invalid or expired, access revoked, or account not active. |
| 403 | scope\_missing | The token does not carry the scope thesis. |
| 403 | plan\_user\_limit | The user signed in beyond the app's plan limit (anonymous sub). |
| 403 | sandbox\_user | Sandbox test users cannot write. |
| 403 | not\_a\_holder | Only holders can post a thesis. |
| 403 | posting\_paused | The user is paused from writing. |
| 400 | invalid\_body, duplicate, invalid\_parameter | See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md#thesis-errors). |
| 404 | not\_found | The post does not exist, was hidden or deleted. |
| 429 | [rate\_limited](https://docs.cabalspy.xyz/cabalspy-id/errors.md#rate_limited) | Too many requests from the user, the IP address or the client\_id. Comes with `Retry-After: 60`. |

Requests are also limited per IP address: 120 reads, 30 writes and 120 reactions per minute. Each client\_id is limited too: about 600 reads and 300 writes per minute across all its visitors. Over a limit the API answers `429 rate_limited` with `Retry-After: 60`.

## Live websocket

A public websocket per token pushes new theses, replies, reactions and removals. No API key or user token is needed, but the URL carries your client\_id as `?client_id=`. `scope=instance` uses the same client\_id.

```text theme={null}
wss://id.cabalspy.xyz/thesis/v1/ws/{chain}/{mint}?client_id=csid_...
wss://id.cabalspy.xyz/thesis/v1/ws/{chain}/{mint}?scope=instance&client_id=csid_...
```

```javascript theme={null}
const ws = new WebSocket(`wss://id.cabalspy.xyz/thesis/v1/ws/solana/${mint}?client_id=${CLIENT_ID}`);
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "thesis") prependCard(msg.data);
  if (msg.type === "reply") addReply(msg.data);
  if (msg.type === "reaction") updateCounts(msg.data.id, msg.data.reactions);
  if (msg.type === "removed") removeCard(msg.data.id);
};
```

| type | data |
| - | - |
| `thesis` | The new thesis. |
| `reply` | The new reply. |
| `reaction` | `{ id, reactions }` with the new counts. |
| `removed` | `{ id }` of a deleted or hidden post. |
| `heartbeat` | Sent every 30 seconds, no data. |

Every message also carries `chain` and `mint`. An invalid chain or token address closes the connection with code 1008, and each IP address can hold at most 20 connections.

Client errors close the connection with these codes; the close reason is the error code:

| Close code | Reason | Meaning |
| - | - | - |
| 4401 | [client\_id\_required](https://docs.cabalspy.xyz/cabalspy-id/errors.md#client_id_required), [invalid\_client](https://docs.cabalspy.xyz/cabalspy-id/errors.md#invalid_client) | No client\_id, or not a valid instance. |
| 4403 | [origin\_not\_allowed](https://docs.cabalspy.xyz/cabalspy-id/errors.md#origin_not_allowed) | The page's origin is not allowed for the instance. |
| 4429 | [rate\_limited](https://docs.cabalspy.xyz/cabalspy-id/errors.md#rate_limited) | Too many connections or requests for the client\_id or IP address. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.