Conventions

Ids

Ids are opaque strings with a prefix: acct_, loc_, vis_, vid_, key_, obs_. Do not parse them.

Times

• RFC 3339.
• A location’s created_at is in UTC.
• A visit’s times, and a video’s published_at, are on the store’s offset: the restaurant’s wall clock. timezone carries its IANA zone.
• Months are YYYY-MM, counted on each store’s own clock.

Money

Integer cents, with currency: "USD". API usage is priced in micro-dollars (1 USD = 1,000,000). Not live yet

Pagination

Lists take limit (1 to 200, default 50) and cursor.

• Pass the previous page’s next_cursor unchanged. Leave it out for the first page.
• next_cursor is null on the last page.
• A changed cursor is 400 parameter_invalid (field cursor).
• Visits page by last update, so a visit can appear again on a later page. Dedupe on id.

Idempotency

Send Idempotency-Key on every POST, PATCH and DELETE. It is required on money calls and location creates.

• Up to 255 printable ASCII characters, no spaces.
• A retry with the same key and body gets the stored answer, with Idempotent-Replayed: true, for 24 hours.
• The same key with a different body is 409 idempotency_conflict.
• A duplicate while the first is still running is 409 idempotency_in_progress.
• A 400 or 5xx answer is not stored, so a corrected retry may reuse the key.

Dry runs

dry_run=true on a create checks and quotes, with the same refusals as a live call. It writes no store. Ids come back null. The Idempotency-Key is still stored.

Request ids

Every answer has a Request-Id header. It equals error.request_id. Quote it to support.

Errors

Every error has one envelope:

{ "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "...", "field": "limit", "doc_url": "https://docs.creatorain.com/errors#parameter_invalid", "request_id": "..." } }

Branch on code. See Errors.

Versioning

• The major version is in the path: /v1.
• Changes inside v1 are additive: new fields, new endpoints, new codes. Ignore fields you do not know.
• A breaking change ships as /v2, with 6 months of overlap.
• A CreatoRain-Version header is reserved. Not live yet

See the Changelog.