Sokko Docs
Platform API

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 /account
curl 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" }
}
FieldMeaning
nameThe name of your own workspace.
billingThe state and the plan of your subscription.
limits.maxWorkspacesWorkspaces your account can hold.
limits.maxAgentsPerWorkspaceAgents one workspace can hold.
limits.agentSeatsExtra agents you bought on top of your plan.
poolAgents in your own workspace plus all your customer workspaces, and the cap of your plan + seats.
credits.balanceCentsThe AI credits of your own workspace, plan credits and purchased credits together.
credits.purchasedCentsThe purchased part of that balance.
credits.transferableCentsWhat you can move to a workspace. Only this amount can move.
sandboxWorkspaceIdThe workspace your recipe tests run in, or null before the first test run.
brandThe 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 GET costs 1. Every other method costs 2, also when it is refused.
  • POST /workspaces/{workspaceId}/memory/search reads, so it costs 1.
  • A message sent in stream mode is a POST (2). A GET of 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."
  }
}
  • code is stable. Write your code against it.
  • message is 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 example externalId: must not start with "_".
  • One error has an extra field: 409 turn_in_progress carries turnId, 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 code is what tells you more.

Error codes

StatusCodeMeaning
400invalid_requestThe body, a query parameter or a cursor is not valid.
400not_supportedThe request asks for something the API does not offer (an OAuth or stdio MCP server).
400unsupported_appThe app cannot be connected through the API.
400mcp_server_url_not_allowedThe 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.
401unauthorizedThe key is missing or not valid.
402billing_inactiveYour subscription does not allow this call. See Credits.
402plan_limitYour agent pool is full, the workspace has its maximum of agents, or your plan lacks the feature.
402credits_exhaustedThe workspace has no credits left.
402insufficient_poolYour purchased credits are too low for this transfer.
402memory_not_enabledMemory is not enabled for your account, or the workspace has none.
402payment_requiredAnother billing rule refused the request.
403forbiddenThe request is not allowed (for example a change to the sandbox workspace).
403workspace_limitYour account holds its maximum of workspaces.
403end_users_disabledAgents for end users are not enabled yet. Send audience: "operator".
404not_foundThe resource does not exist for your account.
409conflictThe request conflicts with the current state. The message says how.
409external_id_conflictThe externalId exists with other fields.
409workspace_deletingThe workspace is being deleted. Only GET and DELETE work on it.
409agent_busyThe agent is starting, stopping, being upgraded or being deleted. Try again when it is ready.
409not_upgradableThe agent has no newer recipe version to move to.
409agent_not_readyThe call needs an agent whose status is ready.
409skill_not_activeA skill you named is not active in the workspace.
409skill_conflictA recipe's skill has the name of a different skill in the workspace.
409mcp_server_conflictA recipe's MCP server has the name of a different server in the workspace.
409mcp_server_not_allowed_for_end_usersThe MCP server cannot be used by an agent for end users. A server with a token needs an https URL.
409turn_in_progressA turn is already running in the conversation. The body carries turnId.
409idempotency_mismatchThe clientMessageId was used before with other content.
409input_requiredThe agent waits for an answer. Send answers, or stop the turn.
409no_pending_inputYou sent answers, and no question waits.
409schedule_existsThe agent already has a schedule with this name.
409recipe_archivedThe recipe is archived: no new version, no new agent, no test run.
409no_testsThe recipe version has no tests to run.
413payload_too_largeThe body, a file or a recipe is over its size limit.
422unprocessableThe body is well formed, and its content is refused (a recipe template, an unknown app or skill).
422unsupported_appA recipe names an app that recipes cannot use.
422invalid_variablesThe variables do not fit the recipe.
422return_url_not_allowedThe returnUrl is not on an origin your account allows.
429rate_limitedOver the request budget. Read Retry-After.
429too_many_streams20 event streams are open. Close one.
429test_queue_fullFive test runs already wait. Retry-After is 60.
500internal_errorA fault on the platform's side. Safe to retry with the same natural key.
503unavailableA part of the platform is not available. Try again later.
503agent_unavailableThe agent could not be reached. Try again later.
503storage_unavailableFile storage is not available. Try again later.
504timeoutThe 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.

On this page