Get started

Authentication

API keys, Bearer auth, scopes, and plan access.

API keys

Every request to the API authenticates with an OpenCharts API key passed as a Bearer token. Keys start with oc_ and are the same keys the OpenCharts MCP server accepts, so one key can power both surfaces.

curl

curl https://www.opencharts.com/api/v1/account \
  -H "Authorization: Bearer oc_your_api_key"

Create and revoke keys in the Developers hub. Keys are shown once, at creation, and stored hashed; OpenCharts never keeps the raw key. If you lose one, revoke it and create a new one.

Scopes

Each key carries one or more scopes, checked per endpoint (the required scope is shown on every operation in the API reference):

Scopes

read

scope

List and fetch resources (GET endpoints).

write

scope

Create, update, and delete resources.

ai

scope

Run AI work: chat, images, video, music, code builds, research, and agent dispatch. Consumes the account's AI credits.

A request whose key lacks the required scope returns 403 with the standard error envelope.

Plan access

The API is available on the Unlimited and Teams plans. Calls from other plans return 403with an upgrade hint. AI-powered endpoints additionally pre-flight and consume the account's AI credits, the same metering Theo uses in-app; check the balance with GET /account/credits.

Key safety

Treat keys as server-side secrets

Never ship an API key in a browser, mobile app, or public repo. Route requests through your own backend, keep keys in environment variables or a secret manager, and rotate by revoking + recreating in the Developers hub.

Every response carries an X-Request-Id header you can quote in support requests, and rate limiting is per key (see Rate limits).