The HTTP API

Sokie's HTTP API lets a script, CI or any tool that speaks HTTP read your servers and act on them, with an API key. It answers at:

https://api.sokie.cloud/v1

Its OpenAPI document is at https://api.sokie.cloud/v1/openapi.json, and needs no key to read. Every operation in it has a name, like listServers, and says the permission it needs.

For an agent, connect Sokie's own MCP server instead: Manage Sokie from your agent has the steps.

Send your key

Make an API key, then send it as a bearer token on every request:

curl https://api.sokie.cloud/v1/servers \
  -H "Authorization: Bearer sokie_ak_…"

The API acts as you, with only the permissions and servers the key was given. Sokie checks the key on every call, so one you revoke, or one that expires, is refused from its next call. A key works in one workspace: to reach another, use a key from there.

Find a server

Most paths take a server's id, not its slug. Get it once from the slug:

curl https://api.sokie.cloud/v1/servers/majestic-lobster-123 \
  -H "Authorization: Bearer sokie_ak_…"

The answer's serverId is what /servers/{serverId}/… takes. GET /servers lists every server the key can see, each with its id.

What it covers

A tool's description changes one of two ways. On a server linked to a repository, use pull-request: production changes when it merges. On one with no repository, use deploy, and send the server's liveDeploymentId as base. If production has moved on since, nothing changes and the answer says STALE_BASE.

/logs takes errors=true for only the calls that didn't succeed, and tool for one tool's. /audit takes serverId for one server's changes, and category for one kind. Logs say what happened in each call, never what was sent. Deploying new source, setting secrets and deleting servers stay with the CLI and the app.

Pages

A list comes back a page at a time:

{ "page": [ … ], "isDone": false, "continueCursor": "…" }

limit sets how many to a page, 25 unless you say, and 100 at most. While isDone is false, send continueCursor back as cursor for the next page:

curl "https://api.sokie.cloud/v1/servers?limit=100&cursor=…" \
  -H "Authorization: Bearer sokie_ak_…"

A query parameter a path doesn't take is refused, so a misspelled filter never reads as applied.

When it's refused

A refusal comes back as JSON, with a code and a sentence that says what to do:

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "The API key “GitHub Actions” can’t deploy on Petstore: it needs Deploys, read and write.",
    "scope": "deploys:write",
    "server": "majestic-lobster-123"
  }
}

The codes are the ones the CLI shows. The status says what kind of refusal it is:

A server the key wasn't given is answered as if it weren't there, with a 404.

Limits

Changing tool descriptions, through either path, is limited to 10 a minute for each person. Past that, the call is refused with a 429 and RATE_LIMITED. One production deploy runs on a server at a time, so a redeploy or restore while another runs answers DEPLOY_IN_PROGRESS.