Skip to main content
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:
  • 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.
For server-to-server writing with your API key, use the Data API 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. 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:* 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.
Never use your secret API key in a browser. For server-side data access use the Data API on api-id.cabalspy.xyz with your API key, the same key as for the main CabalSpy API.
The playground and the public profile pages keep working as before, and the OpenID Connect discovery document and JWKS stay public.

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: