Idempotency

The Operata API is idempotent today by HTTP method — GET, PUT, and DELETE are all safe to retry without coordination. POST endpoints are not yet exposed; when they are, the platform will honor a Stripe-style Idempotency-Key header contract described below.

Endpoint

Any write endpoint under https://api.operata.io

Parameters

Name	Type	Required	Description
`Idempotency-Key`	string (header)	no, not yet honored	Reserved for a future contract. The server accepts the header today but does not act on it. See the rollout plan below.

Response

Today, idempotency is a property of the HTTP method, not of an extra header. The current Operata API behaves as follows on retry:

Method	Endpoint	Idempotent today	Notes
`GET`	every read endpoint	yes	Reads never change state. Retry without coordination.
`PUT`	`/v1/config/json`	yes	Sending the same redaction config body twice yields the same final state. Sending a different body replaces the previous one.
`DELETE`	`/v1/config/REDACTION_CONFIG`	yes	Deleting an already-deleted config returns `404 not_found`. The end state matches.
`POST`	none today	n/a	The current API exposes no `POST` write endpoints. When it does, the rules below apply.

The planned Idempotency-Key contract follows the Stripe pattern:

The key is a client-generated string, opaque to the server, 1–255 characters. UUIDv4 is the recommended shape.
The server stores the response for 24 hours, keyed by the tuple (token, method, path, idempotency_key).
A repeat request with the same key returns the stored response with header Idempotency-Replayed: true.
A repeat request with the same key but a different body returns 409 conflict with code idempotency_conflict.
After the 24-hour window, the key is forgotten and the request executes normally.

Example

Sending the same redaction config twice leaves one final state:

# First request — writes the config.
curl -X PUT -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"REDACTION_CONFIG","value":{"type":"BLACKLIST","fields":["Agent.ARN"]}}' \
  "https://api.operata.io/v1/config/json"

# Same request, sent again — same final state, no duplicate side-effects.
curl -X PUT -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"REDACTION_CONFIG","value":{"type":"BLACKLIST","fields":["Agent.ARN"]}}' \
  "https://api.operata.io/v1/config/json"

import os, uuid, requests

# Generate one key per logical operation, not per HTTP attempt.
# The header is accepted today but not honored — include it now to be ready.
key = str(uuid.uuid4())
headers = {"Idempotency-Key": key, "Content-Type": "application/json"}
body = {"key": "REDACTION_CONFIG", "value": {"type": "BLACKLIST", "fields": ["Agent.ARN"]}}

response = requests.put(
    "https://api.operata.io/v1/config/json",
    auth=(os.environ["OPERATA_GROUP_ID"], os.environ["OPERATA_API_TOKEN"]),
    headers=headers,
    json=body,
)
response.raise_for_status()

Errors

Status	Code	When	Recover
409	`idempotency_conflict`	A future request reuses an `Idempotency-Key` from the last 24 hours with a different body. Reserved; not emitted today.	Either send the original body or generate a new key.
400	`invalid_idempotency_key`	Reserved. The key violates the length or character set rules.	Generate a fresh UUIDv4.

See Errors for shared codes such as 401 unauthorized and 429 rate_limited.

Overview & quickstart

API essentials

Endpoints — Contacts

Endpoints — Logs

Endpoints — Users

Endpoints — Data redaction

Events & webhooks

Streaming & backends

AI & MCP

Endpoint

Parameters

Response

Example

Errors

​Endpoint

​Parameters

​Response

​Example

​Errors

Endpoint

Parameters

Response

Example

Errors