Spoks API Docs

The API uses date-based versions, named after the month they were released. The current version is 2026-07.

Requesting a version

URLs never carry a version — endpoints stay exactly as documented. Pin your integration by sending the X-Api-Version header on every request:

curl https://api.spoks.com/workspaces \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Api-Version: 2026-07"

A pinned version never changes underneath you — breaking changes only ever ship as a new version.

Requests without the header

Requests without X-Api-Version keep working and are pinned to the oldest supported version, so existing integrations never break. The legacy /v1 path prefix behaves exactly the same way.

Treat that as a convenience, not a strategy: when the oldest version is eventually retired, unpinned callers move forward with it. Pin explicitly.

Every response — success or error — carries an X-Api-Version header with the version that actually served the request. Log it: it tells you which version your integration is really running against, whether or not you sent the header yourself.

Unknown or retired versions

Requesting a version that doesn't exist (or has been retired) is a hard 400 with the supported versions listed in the message — the request is not silently served by a newer version. The one exception to the header rule above: this error carries no X-Api-Version, because no version was used.

{
  "statusCode": 400,
  "timestamp": "2026-07-27T12:00:00.000Z",
  "path": "/workspaces",
  "message": "API version '2020-01' is not supported. Supported versions: 2026-07. Requests without the X-Api-Version header use 2026-07.",
  "traceId": ""
}

Support and retirement

A new version is released only when a breaking change is needed — there is no fixed release cadence.
Each version stays supported for at least 12 months after its successor ships.
Retirements are announced in these docs at least 3 months in advance.

What counts as a breaking change

Breaking — only ever ships as a new version:

Removing or renaming an endpoint, response field, or parameter.
Changing a field's type or meaning, or an endpoint's default behaviour.
Making an optional input required, or tightening validation.
Changing the status code of an existing error condition.

Non-breaking — ships to all supported versions:

New endpoints and new optional parameters.
New fields in responses.
Bug fixes.

The API is in beta, so response bodies can gain fields at any time — parse defensively and ignore what you don't recognise, as covered in API basics.

What is not versioned

These are stable across versions and can evolve without a version bump:

Authentication and the x-api-key header.
Rate limits.
The error shape.
The OpenAPI schema endpoint, which always describes the current version.

API versioning