This page describes the core request/response conventions for the SERVOS API, including content types, identifiers, dates, and error formats.
Content type
- Request body: JSON
- Response body: JSON
When sending JSON bodies, use:
Content-Type: application/json
Base URL and scoping
The API is served from the dedicated api subdomain:
https://api.servos.dk/store/v0
The host is fixed — it is not org-subdomained. The organization is derived from the API key, so there is no organization or location segment in the path.
Public visibility rules
Catalog endpoints only return objects that are:
- kept (not soft-deleted), and
- publicly published
If a resource exists but is not public, it behaves like "not found".
Identifiers
SERVOS returns public identifiers as UUID strings for all entities.
- Use the
public_idvalues returned by list endpoints as input to show/availability/cart endpoints. - Treat all identifiers as opaque strings (UUID format).
Dates and times
Dates
Date-only fields use ISO 8601 date format:
YYYY-MM-DD(example:"2026-03-20")
Timestamps
Timestamp fields use ISO 8601 strings (example: "2026-03-20T08:30:00+01:00").
Time zones
Availability responses include a timezone in IANA format (example: "Europe/Oslo").
Clients should:
- display times in the location's timezone, and
- send
starts_atexactly as returned by availability endpoints (including offset)
Rate limiting
Rate limiting is not currently enforced at the API layer. This may change.
You should implement sensible client-side throttling and caching for catalog endpoints.
Versioning strategy
The API is versioned in the URL path (/store/v0/...). There is no version header.
Error shape
Every error the API returns is { "error": "...", "details": { ... } }: a message, and the specifics behind it (empty when there are none). See Errors for examples per status code and the few failures answered before the API runs.
