- 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 scopethesis, so request it at sign-in, for example withdata-scope="openid profile thesis"on the login button.
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. Send it as a header or as a query parameter:
- Where to find it: in the API Dashboard 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:*andhttp://127.0.0.1:*. - Servers: calls without an
OriginorRefererheader, 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.
Base URL
Endpoints
Path parameters:{chain} is one of solana, bnb, base, eth, rh, {mint} the token address, {id} a thesis or reply id.
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.
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.
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 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.
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.
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:

