Showami (1.0)

API key access levels

Every request must include an X-Api-Key header. Keys are issued at one of two access levels:

• Full access — can read and modify resources via any HTTP method.
• Read-only — restricted to GET, HEAD, and OPTIONS requests. Any request using another method is rejected with 403 Forbidden and the body { "message": "Read-only API keys cannot modify resources." }. Use a read-only key for integrations that only need to pull data (reporting, dashboards, audits). The sign-in endpoints (POST /api/v1/users/tokens and POST /users/sign_in) are allowlisted so the key bearer can still exchange credentials for a user token.

Idempotent creation

The create endpoints (POST /api/v1/showings, POST /api/v1/tasks, POST /api/v1/rentals and POST /api/v1/consumers/showings) accept an optional Idempotency-Key header, so a request can be retried safely when its response never arrives (a timeout or dropped connection) without risking a duplicate booking.

• Use a unique value per showing you intend to create, such as a UUID or your own booking id, and send the same value on every retry of that request. Keys are scoped to the authenticated user (for consumer showings, to the consumer) and up to 255 characters.
• Once the original request has succeeded, a retry with the same key creates nothing and returns 200 with the original showing(s), in their current state, plus an Idempotent-Replayed: true response header.
• A retry must send the same request body as the original (the order of JSON keys doesn't matter). Reusing a key with a different body returns 422 with { "message": "This Idempotency-Key was already used with a different request. Use a new key for a new request." } and creates nothing.
• While the original is still being processed, a retry returns 409 Conflict; wait and retry again with the same key.
• If the original failed (any non-200 response), nothing was booked and the key is released, so a retry with the same key is processed as a new request.

Rate limits

Requests are rate limited to keep the API responsive for every integration.

A request over the limit gets 429 Too Many Requests. It's rejected before it reaches the API, so nothing was created or changed and the request is safe to retry.

• Check the status code, not the body. A 429 from the general limit comes from our edge network, so its body may be HTML rather than JSON.
• If the response has a Retry-After header, wait that many seconds before retrying. Otherwise wait at least 10 seconds, then back off exponentially (10s, 20s, 40s…) with some random jitter. Retrying right away keeps the window full and extends the block.
• Send the same Idempotency-Key when you retry a create (see "Idempotent creation").
• Spread bulk work out: a steady 5 requests per second stays under the limit, while a burst of 50 at once uses up the whole window. Use webhooks rather than polling where you can.

These limits may change. We'll give integration partners notice before lowering them. If your integration needs a higher limit, contact us.