Sokko Docs
Platform API

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"
}
FieldMeaning
idThe id you use in every path of this workspace.
externalIdYour own id for the customer.
statusactive, or deleting while a deletion runs.
memorytrue once the workspace has its shared memory. See Memory.
metadataYour own labels. The platform stores them and gives them back. It reads none of them.
agentsThe number of agents in the workspace.
credits.balanceCentsThe stored credit balance. Read the credits for a fresh number.
deletionErrorOnly on a workspace in deleting whose deletion is late. See Delete a workspace.

Create a workspace

POST /workspaces
FieldTypeRules
externalIdstringRequired. 1 to 128 characters, no space at either end, no control character, not starting with _.
namestringRequired. 2 to 80 characters.
memorybooleanOptional, default false. Gives the workspace a shared memory.
metadataobjectOptional. 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 externalId with the same name, memory and metadata answers 200 with the workspace that exists. Nothing is created twice.
  • The same externalId with other fields answers 409 external_id_conflict. To change a workspace, use PATCH.
  • 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 externalId finishes it with the fields of that request, and answers 201.
  • The externalId of a deleted workspace is free again. While the deletion runs, a create with that externalId answers 409 workspace_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

StatusCodeWhen
400invalid_requestA field breaks a rule above.
402billing_inactiveYour subscription is not active, or a payment is past due.
402memory_not_enabledYou sent memory: true and memory is not enabled for your account.
403workspace_limitYour account holds limits.maxWorkspaces workspaces.
409external_id_conflictThe externalId exists with other fields.
409workspace_deletingThe workspace with this externalId is being deleted.
409conflictThe same request is still creating the workspace. Send it again in a moment.
429rate_limitedOver 10 workspace creations in a minute, or over your request budget.

List workspaces

GET /workspaces
QueryMeaning
externalIdOnly the workspace with this external id.
statusactive or deleting. Without it, both.
includeSandboxtrue adds your sandbox workspace. It is left out by default.
limit1 to 100, default 25.
cursorThe 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.

StatusCodeWhen
400invalid_requestNeither name nor metadata, or a bad value.
403forbiddenThe workspace is your sandbox workspace.
404not_foundNo such workspace in your account.
409workspace_deletingThe 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:

  1. Every agent of the workspace, with its files. An agent that is still being set up is cancelled.
  2. The conversations, skills, MCP servers and their tokens, stored files and app connections.
  3. The credits: the last spend is booked, then what the workspace did not spend goes back to your purchased credits.
  4. The shared memory.
  5. 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.

StatusCodeWhen
403forbiddenThe workspace is your sandbox workspace. It cannot be deleted.
404not_foundNo such workspace in your account, or its deletion has ended.
409conflictThe 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.maxWorkspaces workspaces (see GET /account). The default is 25. The sandbox workspace does not count.
  • One workspace holds up to limits.maxAgentsPerWorkspace agents. The default is 2.
  • 10 workspace creations per minute.

Ask the Sokko team to raise a limit.

On this page