# 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: ```json { "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](/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](/changelog/).