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
| Thing | What it is |
|---|---|
| Account | Your company. It has one subscription, one pool of agents and one pool of AI credits. |
| Workspace | One customer of yours. Its agents, skills, connected apps, memory and credits are separate from every other workspace. |
| Agent | An always-on agent in one workspace. You give it a name and instructions, and it answers the messages you send. |
| Conversation | One thread between an agent and one end user of your product. You name the end user with your own id. |
| Recipe | Your 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:
2500is $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 thenextCursorof the previous page.nextCursorisnullon 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:
| Call | Key | Same key, same fields | Same key, other fields |
|---|---|---|---|
| Create a workspace | externalId | 200 with the workspace | 409 external_id_conflict |
| Create an agent | externalId (optional) | 200 with the agent | 409 external_id_conflict |
| Move credits | requestId | 200 with the transfer | 409 conflict |
| Send a message | clientMessageId | The first turn, no new one | 409 idempotency_mismatch |
| Create a recipe | slug | 200 with the recipe | 409 conflict |
| Create a schedule | name | 409 schedule_exists | 409 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_xxxCheck 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
Authentication
Keys, rate limits and the error format.
Workspaces
One workspace per customer.
Credits
The pool, transfers, usage and automatic top-up.
Agents
Create, change, suspend and delete agents.
Skills and MCP servers
Give an agent skills and tools of your own.
Integrations
Let your customer connect an app to an agent.
Memory
The shared memory of a workspace.
Conversations
Messages, the event stream, questions and attachments.
Webhooks
Signed events for your server.
Schedules
Tasks an agent runs on a cron schedule.
Recipes
A versioned template for your agents.
Testing recipes
Test runs in your sandbox workspace.
Data and privacy
What is stored, who can read it, how to delete it.
Limits
Every numeric limit in one table.