API basics
Base URL, formats and conventions used across the API.
The Spoks Public API is a single REST API over HTTPS. Everything speaks JSON.
Base URL
https://api.spoks.comAll endpoints are relative to this base and grouped by resource in the sidebar.
A legacy /v1 prefix also works, but the plain paths shown throughout these
docs are the canonical form.
Requests
- Send
Content-Type: application/jsonon any request that has a body. - Request bodies are limited to 2 MB — larger bodies are rejected with
413. - Authenticate every request with your API key — the public embed listings below are the only exception.
Responses
- Responses are JSON. One exception: request the contacts list with an
Accept: text/csv(or XLSX) header and you get a file download instead. - The API is in beta — response bodies can gain or change fields, so parse defensively and ignore what you don't recognise.
- Most list endpoints are paged and filterable — see Pagination & filtering.
- Errors follow a consistent shape — see Errors.
Workspace scoping
Your API key identifies your workspace. Workspace endpoints (/contacts,
/products, /posts, ...) carry no workspace id in the path: the API resolves
the workspace, and the region your data lives in, from the key.
The exception is the public embed listings
(/{workspaceId}/posts, /{workspaceId}/public-posts), which take the
workspace id in the path because they are called without a key. They're built
for embedding in a browser — any site can call them — and skip the rate
limits.
Rate limits
Keys get 60 requests per minute, counted across all API instances. Bursts
are throttled harder: more than about 20 requests in quick succession can
hit the limit before the per-minute cap does. Either way the response is a
429 with a Retry-After header telling you how
many seconds to wait — pace your requests instead of sending bursts.
Requests without a valid key are throttled per client IP.
OpenAPI schema
The whole API is described in an OpenAPI document at
https://api.spoks.com/openapi.json —
no key needed. Handy for generating typed clients.
Conventions
- Timestamps are in ISO 8601 format, in UTC (e.g.
2026-01-01T12:00:00.000Z). - Resource identifiers are opaque strings — don't read anything into their format.