API: /v1/record

Overview

The idempotency API is a two-step flow:

Check or lock with POST /v1/record to see if a record already exists or to acquire a lock.
Save with PUT /v1/record once your handler finishes.

There are also read/delete helpers:

GET /v1/record – fetch a cached record.
DELETE /v1/record – remove a cached record.

Endpoints

POST /v1/record – check/lock by scope + key.
PUT /v1/record – save a record body + metadata.
GET /v1/record – fetch a cached record.
DELETE /v1/record – remove a cached record.

Request schema

POST /v1/record

json

{
  "scope": "orders",
  "key": "order-001",
  "ttlSeconds": 86400
}

PUT /v1/record

json

{
  "scope": "orders",
  "key": "order-001",
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "status": "paid"
  },
  "ttlSeconds": 86400
}

Headers:

Authorization: Bearer <api_key> — required.
Content-Type: application/json.

Responses

POST /v1/record

json

{
  "cached": true,
  "record": {
    "status": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "...": "..."
    }
  }
}

json

{
  "cached": false,
  "locked": true
}

json

{
  "cached": false,
  "locked": false,
  "retryAfterMs": 1500
}

PUT /v1/record

json

{
  "ok": true
}

GET /v1/record

json

{
  "cached": false
}

json

{
  "cached": true,
  "record": {
    "status": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "...": "..."
    }
  }
}

DELETE /v1/record

json

{
  "ok": true,
  "existed": true
}

Error cases

Status	Cause
400	Missing `scope`/`key` or invalid body
403	Forbidden resource (missing/invalid API key)
429	Usage limit exceeded while acquiring the lock
500	Unexpected server error

API: /v1/record

Overview

Endpoints

Request schema

Responses

Error cases

Related guides