API overview
Base URL, authentication, and the shape of every ChatPlotDB API response.
Base URL
All endpoints are served under /api on your ChatPlotDB backend. For the
managed service that is the app host; for a self-hosted deployment it is
whatever you have configured.
Authentication
Requests carry a bearer token:
Authorization: Bearer <token>Tokens are issued by the Simplifying AI identity service, not by ChatPlotDB itself. Guest sessions receive a restricted token: fewer models, a starting credit grant, and no access to organization resources.
These are session tokens, not API keys
Authentication is user-scoped JWT. If you are looking for long-lived server-to-server API keys, see the open question in Getting help: that surface is not documented here because it is not in the product yet.
Credits on every response
Metered endpoints return your remaining balance in a header:
X-Credits-Remaining: 412.75A request that would overdraw returns 402 with an upsell payload rather than
failing opaquely.
Endpoint groups
| Group | Covers |
|---|---|
| Chat | Ask questions, resume paused runs, stream results |
| Threads | List, rename, archive; per-thread messages and files |
| Configs | The registry: CRUD, YAML upload, versions, stitched, DynamoDB |
| Files | Upload, library, attach, share, schema peek |
| Dashboards | Dashboards, cards, refresh, controls, alerts, health |
| Models | The selectable model sets |
| Usage | Per-user, per-thread, and per-org consumption |
Errors
Errors return a JSON envelope with a machine-readable class and a human message. SQL errors carry a taxonomy: the class tells you whether the query was malformed, the permission was missing, or the source was unreachable.