Workspaces
Create one workspace for each of your customers, then list, read, rename and delete them.
A workspace holds everything of one customer of yours: its agents, skills, MCP servers, connected apps, shared memory and AI credits. Nothing crosses from one workspace to another.
All paths below are relative to https://sokko.ai/api/v1.
The workspace object
{
"id": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
"externalId": "cust_1042",
"name": "Bakkerij Janssens",
"status": "active",
"memory": true,
"metadata": { "plan": "pro", "region": "be" },
"agents": 2,
"credits": { "balanceCents": 1840 },
"createdAt": "2026-11-20T09:14:02.118Z",
"updatedAt": "2026-11-20T09:14:03.402Z"
}| Field | Meaning |
|---|---|
id | The id you use in every path of this workspace. |
externalId | Your own id for the customer. |
status | active, or deleting while a deletion runs. |
memory | true once the workspace has its shared memory. See Memory. |
metadata | Your own labels. The platform stores them and gives them back. It reads none of them. |
agents | The number of agents in the workspace. |
credits.balanceCents | The stored credit balance. Read the credits for a fresh number. |
deletionError | Only on a workspace in deleting whose deletion is late. See Delete a workspace. |
Create a workspace
POST /workspaces| Field | Type | Rules |
|---|---|---|
externalId | string | Required. 1 to 128 characters, no space at either end, no control character, not starting with _. |
name | string | Required. 2 to 80 characters. |
memory | boolean | Optional, default false. Gives the workspace a shared memory. |
metadata | object | Optional. Up to 20 keys. A key has 1 to 64 characters, a value is a string of up to 500. |
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",
"memory": true,
"metadata": { "plan": "pro", "region": "be" }
}'The answer is the workspace object, with 201 for a new workspace.
One workspace per externalId
externalId makes the call safe to repeat:
- The same
externalIdwith the samename,memoryandmetadataanswers 200 with the workspace that exists. Nothing is created twice. - The same
externalIdwith other fields answers 409external_id_conflict. To change a workspace, usePATCH. - After a timeout or a 5xx, send the same request again. It finishes what the
first attempt started. While that first attempt has not finished, the
workspace does not exist yet: the next request for its
externalIdfinishes it with the fields of that request, and answers 201. - The
externalIdof a deleted workspace is free again. While the deletion runs, a create with thatexternalIdanswers 409workspace_deleting.
If memory is true and the answer shows "memory": false, the workspace
exists and its memory could not be set up at that moment. Send the same create
request again to finish it.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A field breaks a rule above. |
| 402 | billing_inactive | Your subscription is not active, or a payment is past due. |
| 402 | memory_not_enabled | You sent memory: true and memory is not enabled for your account. |
| 403 | workspace_limit | Your account holds limits.maxWorkspaces workspaces. |
| 409 | external_id_conflict | The externalId exists with other fields. |
| 409 | workspace_deleting | The workspace with this externalId is being deleted. |
| 409 | conflict | The same request is still creating the workspace. Send it again in a moment. |
| 429 | rate_limited | Over 10 workspace creations in a minute, or over your request budget. |
List workspaces
GET /workspaces| Query | Meaning |
|---|---|
externalId | Only the workspace with this external id. |
status | active or deleting. Without it, both. |
includeSandbox | true adds your sandbox workspace. It is left out by default. |
limit | 1 to 100, default 25. |
cursor | The nextCursor of the previous page. |
Workspaces come oldest first.
curl "https://sokko.ai/api/v1/workspaces?externalId=cust_1042" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"data": [
{
"id": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
"externalId": "cust_1042",
"name": "Bakkerij Janssens",
"status": "active",
"memory": true,
"metadata": { "plan": "pro", "region": "be" },
"agents": 2,
"credits": { "balanceCents": 1840 },
"createdAt": "2026-11-20T09:14:02.118Z",
"updatedAt": "2026-11-20T09:14:03.402Z"
}
],
"nextCursor": null
}Errors: 400 invalid_request (a bad status, limit or cursor).
Read a workspace
GET /workspaces/{workspaceId}curl https://sokko.ai/api/v1/workspaces/7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11 \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"The answer is the workspace object. Errors: 404 not_found.
Rename a workspace
PATCH /workspaces/{workspaceId}Send name, metadata or both. metadata replaces the stored object: send
every key you want to keep.
curl -X PATCH https://sokko.ai/api/v1/workspaces/7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11 \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Janssens Bakery", "metadata": { "plan": "enterprise", "region": "be" } }'The answer is the workspace object. externalId and memory cannot be
changed.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | Neither name nor metadata, or a bad value. |
| 403 | forbidden | The workspace is your sandbox workspace. |
| 404 | not_found | No such workspace in your account. |
| 409 | workspace_deleting | The workspace is being deleted. |
Delete a workspace
DELETE /workspaces/{workspaceId}curl -X DELETE https://sokko.ai/api/v1/workspaces/7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11 \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{ "id": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11", "status": "deleting" }The answer is 202. The deletion runs in the background, and you can send the call again without harm. It removes, in this order:
- Every agent of the workspace, with its files. An agent that is still being set up is cancelled.
- The conversations, skills, MCP servers and their tokens, stored files and app connections.
- The credits: the last spend is booked, then what the workspace did not spend goes back to your purchased credits.
- The shared memory.
- The workspace itself.
The deletion works one step at a time and waits for each agent to be removed,
so it takes a few minutes. While it runs, the workspace has
"status": "deleting". GET and DELETE work on it, and every other call
answers 409 workspace_deleting, a credit transfer included. When it ends, the
workspace answers 404, its externalId is free, and your endpoints get the
event workspace.deleted with workspaceId and externalId.
When a deletion is late, the workspace object carries deletionError. That
is the case when the workspace is still deleting more than one hour after
your request because an agent does not stop, or when a step of the deletion
failed and waits for its next try:
{
"id": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
"status": "deleting",
"deletionError": {
"code": "deletion_delayed",
"message": "The deletion of this workspace takes longer than expected. It is tried again automatically. The unspent credits return when it is complete. Contact support if this message stays."
}
}The example shows only the fields that matter here. You do not have to do anything: the deletion continues by itself, and the unspent credits return when it is complete. The field is absent while a deletion runs as it should.
A deletion cannot be undone. The memory and the conversations of the workspace are gone.
The usage records of the workspace are kept for billing.
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The workspace is your sandbox workspace. It cannot be deleted. |
| 404 | not_found | No such workspace in your account, or its deletion has ended. |
| 409 | conflict | The workspace holds records that the deletion cannot remove. Write to support. |
A delete works whatever the state of your subscription is.
Limits
- Your account holds up to
limits.maxWorkspacesworkspaces (seeGET /account). The default is 25. The sandbox workspace does not count. - One workspace holds up to
limits.maxAgentsPerWorkspaceagents. The default is 2. - 10 workspace creations per minute.
Ask the Sokko team to raise a limit.