Sokko Docs
Platform API

Platform API

Run agents inside your own product: one workspace for each of your customers, created and driven from your server.

The Platform API lets you offer agents as a feature of your own product. Your server creates a workspace for each of your customers, creates agents in it, and passes messages between your users and those agents. Your customers never sign in to Sokko: your product is the only interface they use.

Everything on these pages is an HTTPS call from your server with a platform key.

The model

ThingWhat it is
AccountYour company. It has one subscription, one pool of agents and one pool of AI credits.
WorkspaceOne customer of yours. Its agents, skills, connected apps, memory and credits are separate from every other workspace.
AgentAn always-on agent in one workspace. You give it a name and instructions, and it answers the messages you send.
ConversationOne thread between an agent and one end user of your product. You name the end user with your own id.
RecipeYour standard, versioned way to build an agent: instructions with variables, skills, MCP servers, apps, schedules. You apply it once per customer.

You pay for everything through your own subscription. A workspace has no plan of its own: it draws on your agent pool, and you move AI credits to it. See Credits.

Get access

Ask the Sokko team

The Platform API is enabled per account. Write to support@sokko.ai from a workspace with a paid plan. The team turns the API on for that workspace and sets your limits (workspaces, agents per workspace, requests per minute), whether your workspaces can have memory, your brand (the name your agents say they are the agent of, and the name and logo of the app-connect page), and the origins your connect flow can return to.

Create a platform key

In the dashboard, open Settings → API Keys. A Platform keys card is there once your account is enabled. Only an owner of the workspace can create a key. Copy the key now: it is shown once.

Keep the key on your server

A platform key can create, read and delete every workspace of your account. Never put it in a browser or a mobile app. See Authentication.

Conventions

  • The base URL is https://sokko.ai/api/v1.
  • Request and response bodies are JSON. A field the API does not know is an error (400 invalid_request), not ignored.
  • An id is a lowercase UUID (a schedule id is a short string). Every time is an ISO 8601 string in UTC.
  • Money is AI credits in cents: 2500 is $25.00 of credits.
  • An id that belongs to another account answers 404, the same as an id that does not exist.
  • A list answers { "data": [...], "nextCursor": "..." }. Pass ?limit= (1 to 100, default 25) and ?cursor= with the nextCursor of the previous page. nextCursor is null on the last page.

Safe retries

No call needs an idempotency header. Each create has a natural key, so you can send the same request again after a timeout:

CallKeySame key, same fieldsSame key, other fields
Create a workspaceexternalId200 with the workspace409 external_id_conflict
Create an agentexternalId (optional)200 with the agent409 external_id_conflict
Move creditsrequestId200 with the transfer409 conflict
Send a messageclientMessageIdThe first turn, no new one409 idempotency_mismatch
Create a recipeslug200 with the recipe409 conflict
Create a schedulename409 schedule_exists409 schedule_exists

A create that is new answers 201. Two creates answer 202 instead, because their work continues in the background: an agent from a recipe whose skills must first be installed, and a skill import. A delete of a workspace answers 202 for the same reason.

Webhooks are delivered at least once. An event can arrive twice, so make your handler safe to repeat.

Quickstart

These steps take you from a key to an agent's answer in about five minutes. Set the key first:

export SOKKO_PLATFORM_KEY=sk_live_xxx

Check the key

curl https://sokko.ai/api/v1/account \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"

The answer shows your limits, your agent pool and your credit balance.

Create a workspace for one customer

externalId is your own id for that customer.

curl https://sokko.ai/api/v1/workspaces \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "cust_1042", "name": "Bakkerij Janssens" }'
{
  "id": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "externalId": "cust_1042",
  "name": "Bakkerij Janssens",
  "status": "active",
  "memory": false,
  "metadata": {},
  "agents": 0,
  "credits": { "balanceCents": 0 },
  "createdAt": "2026-11-20T09:14:02.118Z",
  "updatedAt": "2026-11-20T09:14:03.402Z"
}

Keep the id. The next calls use it as $WORKSPACE.

Move credits to the workspace

A new workspace has no credits, and an agent cannot be created without them. This moves $20.00 from your purchased credits. requestId is a UUID you generate.

curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/credits \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 2000, "requestId": "0b6f2d1e-7c3a-4e58-9a41-5d2c8e7f1a90" }'

Create an agent

curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order desk",
    "instructions": "You answer customers of Bakkerij Janssens. Opening hours: Tuesday to Sunday, 7:00 to 18:00. Orders for the next day close at 16:00.",
    "audience": "end_users"
  }'

The answer has the agent's id and "status": "provisioning". Read the agent until its status is ready. This usually takes about a minute.

curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"

If the create answers 403 end_users_disabled, agents for end users are not enabled yet. The Sokko team enables them for the platform. Until then, send "audience": "operator". See Agents.

Open a conversation and send a message

externalUserId is your own id for the person who writes.

curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/conversations \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_88213" }'

Send a message and wait up to 60 seconds for the answer:

curl "https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/conversations/$CONVERSATION/messages?wait=60" \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Can I still order 20 croissants for tomorrow?" }'
{
  "id": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "conversationId": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
  "status": "completed",
  "text": "Yes. Orders for tomorrow close at 16:00 today.",
  "tools": [],
  "createdAt": "2026-11-20T09:21:40.512Z",
  "finishedAt": "2026-11-20T09:21:46.031Z"
}

To show the answer while the agent writes it, use the event stream. See Conversations.

Reference

On this page