Skip to content

Authentication

Send your API key with every request, so the API knows which workspace is asking.

API keys

Admins and owners create API keys in Settings, then API keys. Send the key in the Authorization header as a bearer token:

Requestbash
curl https://api.cogitable.ai/v1/runs/run_8f3k2 \
  -H "Authorization: Bearer cg_live_4f2a..."

A key belongs to one workspace.

Treat a key like a password

Keep it out of code and logs, and revoke it in Settings if it leaks.

Live and test keys

  • Keys that start cg_live_ start real runs and spend credits.
  • Keys that start cg_test_ return sample data and spend nothing. Use them while you build. A test run has no page in the app, so its url points to this page.

Scopes

A scope is one thing a key is allowed to do. Each key holds only the scopes you choose when you create it. A request outside them fails with missing_scope.

runs:write
Start runs and cancel them.
runs:read
Read a run’s status and its personas’ progress, and list the workspace’s sites.
reports:read
Read finished reports and their findings.
test-accounts:write
Reserved for test-account endpoints that aren’t available yet. It allows nothing today.