Safe writes, dry-run & specs

Write endpoints are built for real integrations: retry them safely, preview them without committing, and generate a client from a spec that is always in sync with the routes.

Idempotent writes

Network hiccups happen. Send an Idempotency-Key header on a create/update/delete and the API guarantees the operation runs at most once for that key:

POST /v1/clients
Authorization: Bearer redz_live_...
Idempotency-Key: 6f9a2c-create-acme
Content-Type: application/json

{ "name": "Acme Builders" }

• A retry with the same key and body replays the original result, marked Idempotent-Replayed: true — and does not consume quota twice.
• Reusing a key with a different body returns 409 idempotency_key_reuse.
• Firing the same key twice at once returns 409 idempotency_in_progress on the duplicate.

Dry-run

Validate a write — and preview a delete — without changing anything. Add the header X-Dry-Run: 1 or the query ?dry_run=1:

DELETE /v1/equipment/88?dry_run=1

→ { "data": { "id": 88, "deleted": false, "dry_run": true,
         "mode": "soft", "would_delete": [...], "would_keep": [...] } }

Dry-run runs the full validation and dependency check, so it is the safe way to see whether a write would succeed — and what a delete would touch — before you commit.

OpenAPI, reference & Postman

The spec and docs are generated live from the route registry on every request, so they can never fall out of step with what the API actually serves.

These three surfaces are public and unmetered — you can explore the reference before you even issue a token.