API: /v1/record

Overview

The idempotency API is a two-step flow:

1. Check or lock with POST /v1/record to see if a record already exists or to acquire a lock.
2. 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

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

PUT /v1/record

{
  "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.

Data handling

The saved body is returned on future cache hits, so treat it as operational response data. Do not store card data, passwords, access tokens, session cookies, long-lived secrets, or unnecessary personal data in idempotency records. Prefer stable resource ids and status metadata.

Syllecta enforces request guardrails for this surface:

• ttlSeconds must be positive and cannot exceed the configured maximum.
• saved bodies are capped by IDEMPOTENCY_MAX_RECORD_BODY_BYTES.
• record TTL is capped by IDEMPOTENCY_MAX_RECORD_TTL_SECONDS.

These limits are not a substitute for data minimization. They prevent accidental long-lived or oversized idempotency records from becoming general-purpose customer-data storage.

Responses

POST /v1/record

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

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

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

PUT /v1/record

{
  "ok": true
}

GET /v1/record

{
  "cached": false
}

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

DELETE /v1/record

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

Error cases

Related guides

• Idempotency
• Security and data protection
• Quickstart