Authentication
Platform keys, the Authorization header, rate limits, and the one error format of the Platform API.
Every call to the Platform API carries a platform key. A platform key
belongs to your account, not to a person, and it works on
https://sokko.ai/api/v1 only.
Platform keys
Create a key in the dashboard under Settings → API Keys, in the Platform keys card. The card shows only when the Platform API is enabled for your workspace.
- Only an owner of the workspace, signed in to the dashboard, can create or revoke a platform key. A key cannot create another key.
- The key is shown once. Only a hash is stored. If you lose it, revoke it and create a new one.
- A key has a name (1 to 64 characters) and, if you choose, an expiry of up to 365 days. Without an expiry it works until you revoke it.
- An account can hold 20 live keys. Use one key per environment or service, so that you can revoke one without stopping the others.
- Revoking a key stops it at once.
Platform keys start with sk_live_, like the keys of the
sokko CLI, but the two kinds are not interchangeable.
A CLI key answers 401 on /api/v1. A platform key is refused everywhere else.
Send the key
Send the key as a bearer token:
curl https://sokko.ai/api/v1/account \
-H "Authorization: Bearer sk_live_xxx"The header x-api-key: sk_live_xxx works too.
A platform key can create, read and delete every workspace of your account. Keep it on your server. Never send it to a browser, a mobile app or an end user. The API has no token for browsers: your front end calls your server, and your server calls the API.
Every key problem gives the same answer, 401 unauthorized: no key, a wrong,
revoked or expired key, a key that is not a platform key, and an account that
the Sokko team suspended.
While the Platform API is not enabled, every path under /api/v1 answers 404
not_found.
Read your account
GET /accountcurl https://sokko.ai/api/v1/account \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"id": "5a0c9e1b-3d7f-4c2a-b8e6-1f4d7a9c2e30",
"name": "Acme Software",
"status": "active",
"billing": { "status": "active", "plan": "bakery" },
"limits": { "maxWorkspaces": 25, "maxAgentsPerWorkspace": 2, "agentSeats": 20 },
"pool": { "agents": 7, "agentsLimit": 24 },
"credits": { "balanceCents": 48250, "purchasedCents": 30000, "transferableCents": 30000 },
"sandboxWorkspaceId": null,
"brand": { "name": "Acme", "logoUrl": "https://acme.example/logo.png" }
}| Field | Meaning |
|---|---|
name | The name of your own workspace. |
billing | The state and the plan of your subscription. |
limits.maxWorkspaces | Workspaces your account can hold. |
limits.maxAgentsPerWorkspace | Agents one workspace can hold. |
limits.agentSeats | Extra agents you bought on top of your plan. |
pool | Agents in your own workspace plus all your customer workspaces, and the cap of your plan + seats. |
credits.balanceCents | The AI credits of your own workspace, plan credits and purchased credits together. |
credits.purchasedCents | The purchased part of that balance. |
credits.transferableCents | What you can move to a workspace. Only this amount can move. |
sandboxWorkspaceId | The workspace your recipe tests run in, or null before the first test run. |
brand | The name your agents say they are the agent of, and the name and logo of the app-connect page. |
Errors: 401 unauthorized, 429 rate_limited.
Rate limits
Each account has a budget of requests per minute. The default is 300, and the Sokko team can change it for your account.
- A
GETcosts 1. Every other method costs 2, also when it is refused. POST /workspaces/{workspaceId}/memory/searchreads, so it costs 1.- A message sent in stream mode is a
POST(2). AGETof a stream costs 1. - Creating a workspace has a second, smaller budget: 10 per minute.
- At most 20 event streams can be open at once per account.
The window is fixed: it starts with your first request and lasts 60 seconds.
A request over the budget answers 429 with the header Retry-After, in
seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "Too many requests. Try again later." } }Wait for the number of seconds in Retry-After, then send the request again. A
21st event stream answers 429 too_many_streams with Retry-After: 5.
Errors
Every error has the same body:
{
"error": {
"code": "external_id_conflict",
"message": "A workspace with this externalId exists with other fields."
}
}codeis stable. Write your code against it.messageis for a developer. It can change. Do not parse it.- A body that fails validation answers 400
invalid_request. The message names the first field with a problem, for exampleexternalId: must not start with "_". - One error has an extra field: 409
turn_in_progresscarriesturnId, the id of the turn that is running. - A message never names a supplier of the platform. When the cause is on the
platform's side, the message is the general sentence of its status, and the
codeis what tells you more.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body, a query parameter or a cursor is not valid. |
| 400 | not_supported | The request asks for something the API does not offer (an OAuth or stdio MCP server). |
| 400 | unsupported_app | The app cannot be connected through the API. |
| 400 | mcp_server_url_not_allowed | The URL of an MCP server is refused: it is not a full web address, or it has a port, a credential or a #fragment that is not allowed. |
| 401 | unauthorized | The key is missing or not valid. |
| 402 | billing_inactive | Your subscription does not allow this call. See Credits. |
| 402 | plan_limit | Your agent pool is full, the workspace has its maximum of agents, or your plan lacks the feature. |
| 402 | credits_exhausted | The workspace has no credits left. |
| 402 | insufficient_pool | Your purchased credits are too low for this transfer. |
| 402 | memory_not_enabled | Memory is not enabled for your account, or the workspace has none. |
| 402 | payment_required | Another billing rule refused the request. |
| 403 | forbidden | The request is not allowed (for example a change to the sandbox workspace). |
| 403 | workspace_limit | Your account holds its maximum of workspaces. |
| 403 | end_users_disabled | Agents for end users are not enabled yet. Send audience: "operator". |
| 404 | not_found | The resource does not exist for your account. |
| 409 | conflict | The request conflicts with the current state. The message says how. |
| 409 | external_id_conflict | The externalId exists with other fields. |
| 409 | workspace_deleting | The workspace is being deleted. Only GET and DELETE work on it. |
| 409 | agent_busy | The agent is starting, stopping, being upgraded or being deleted. Try again when it is ready. |
| 409 | not_upgradable | The agent has no newer recipe version to move to. |
| 409 | agent_not_ready | The call needs an agent whose status is ready. |
| 409 | skill_not_active | A skill you named is not active in the workspace. |
| 409 | skill_conflict | A recipe's skill has the name of a different skill in the workspace. |
| 409 | mcp_server_conflict | A recipe's MCP server has the name of a different server in the workspace. |
| 409 | mcp_server_not_allowed_for_end_users | The MCP server cannot be used by an agent for end users. A server with a token needs an https URL. |
| 409 | turn_in_progress | A turn is already running in the conversation. The body carries turnId. |
| 409 | idempotency_mismatch | The clientMessageId was used before with other content. |
| 409 | input_required | The agent waits for an answer. Send answers, or stop the turn. |
| 409 | no_pending_input | You sent answers, and no question waits. |
| 409 | schedule_exists | The agent already has a schedule with this name. |
| 409 | recipe_archived | The recipe is archived: no new version, no new agent, no test run. |
| 409 | no_tests | The recipe version has no tests to run. |
| 413 | payload_too_large | The body, a file or a recipe is over its size limit. |
| 422 | unprocessable | The body is well formed, and its content is refused (a recipe template, an unknown app or skill). |
| 422 | unsupported_app | A recipe names an app that recipes cannot use. |
| 422 | invalid_variables | The variables do not fit the recipe. |
| 422 | return_url_not_allowed | The returnUrl is not on an origin your account allows. |
| 429 | rate_limited | Over the request budget. Read Retry-After. |
| 429 | too_many_streams | 20 event streams are open. Close one. |
| 429 | test_queue_full | Five test runs already wait. Retry-After is 60. |
| 500 | internal_error | A fault on the platform's side. Safe to retry with the same natural key. |
| 503 | unavailable | A part of the platform is not available. Try again later. |
| 503 | agent_unavailable | The agent could not be reached. Try again later. |
| 503 | storage_unavailable | File storage is not available. Try again later. |
| 504 | timeout | The agent did not answer in time. |
Every other status of 500 or above carries the code internal_error.
A turn that fails does not fail the HTTP call that reads it. The turn carries
its own error.code. See
Conversations.