Versioning & changelog
How the API is versioned
The API is versioned in the URL path. Every endpoint lives under /v1:
https://api.zeemaps.com/v1/...
A new major version (/v2) would be introduced only for breaking changes, and /v1 would
continue to run alongside it during a deprecation window.
What v1 guarantees
While v1 is current, we treat these as stable:
- Resource URLs and HTTP methods.
error.codevalues and the HTTP status mapped to each (see Errors).- Field names and types on existing responses.
- The owned-only model, Bearer authentication, and the pagination envelope.
What may change without a new version
Additive, backward-compatible changes can land within v1 at any time. Build clients to
tolerate them:
- New endpoints, and new optional fields on existing responses.
- New
enumvalues (e.g. an additional markertypeor jobstatus). Don’t treat the current enum lists as exhaustive — ignore values you don’t recognize rather than failing. - New optional request parameters with safe defaults.
- Tightened prose / examples in the spec and these docs.
Practical guidance: parse JSON leniently, branch on error.code not on message text, and
don’t hard-code the set of enum values.
Deprecation policy
When something must change incompatibly:
- The change ships in a new major version (
/v2);/v1keeps working. - Deprecations are announced in this changelog with a migration note and a sunset date.
- The previous version stays available through its deprecation window before removal.
Keeping in sync with the spec
These docs are generated from zeemaps-api-spec.yaml, the machine-readable source of
truth. The API Reference is rebuilt from that file whenever it
changes, so the reference never drifts from the contract.
Changelog
v1
The full v1 surface is available: identity
(GET /v1/me), maps
(list/get/create/update/delete plus
lifecycle), markers (CRUD, search, and bulk import/delete), schema and demographics
discovery, sharing, image render with the jobs endpoint, and per-key rate limiting with the
X-RateLimit-* headers.