Overview

This reference is public. Credentials are not: keys are issued at onboarding, and there is no self-serve signup. The reference is also canonical — the field names on the concept pages are the names the API returns, and integrations are built against what is written here.

https://api.saifuro.com/v1

All requests use TLS. Bodies are JSON; responses are JSON unless an endpoint says otherwise. The API exposes 29 operations across 23 paths.

The host answers. An unauthenticated request to any path returns the documented 401 envelope, request_id included — that is everything an outsider can see, because keys are issued at onboarding. The parts of the system you can check without holding any key are the signed verdicts and the public key set.

What every endpoint shares

Environments

Sandbox and production, and where they differ

Authentication and keys

Two key classes, what each may reach, what rotation does

Errors and status codes

The envelope, the seven codes, and four behaviours that surprise people

Pagination

Cursors, their lifetime, and the rule that invalidates one mid-walk

Rate limits

A sliding window per key, and where the numbers live

Versioning and deprecation

What may change under /v1 without warning, and what may not

Object ids

Every prefix the system emits, and which two to store

Idempotency

Every POST accepts an Idempotency-Key header. Retrying with the same key within 24 hours returns the original result with Idempotency-Replayed: true. The same key with a different body returns 409 idempotency_conflict — a retry is a retry, not a second attempt with new numbers.

curl -X POST https://api.saifuro.com/v1/authorizations \
  -H "Authorization: Bearer ak_live_..." \
  -H "Idempotency-Key: 7f9c64d1-order-4412" \
  -d '{ "amount": 340.00, "currency": "USD", "recipient": "vendor:acme_saas", "category": "saas" }'

Errors replay too

Errors are cached the same way. A 4xx produced under an idempotency key replays for 24 hours, so fix the body and use a new key rather than retrying the old one.

The kill switch

Enforcement is reversible in one call. POST /v1/enforcement with {"mode": "observe"} returns the environment to pass-through immediately, using your own organization key, without opening a ticket and without us being awake.

Request

curl -X POST https://api.saifuro.com/v1/enforcement \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "mode": "observe" }'

Response

{
  "mode": "observe",
  "since": "2026-09-02T12:00:00Z"
}

GET /v1/enforcement returns the same shape — the current mode and since when it began. The body accepts observe or enforce and nothing else, the key must be an organization key, and the change is effective on the next decision. The call is per environment: a sandbox key flips the sandbox.

Which state produced a given decision is recorded on the decision itself, in its mode field, and that is what survives into the log and the exports. There is no endpoint that returns the history of the switch itself — see known gaps.

OpenAPI

The machine-readable contract lives at docs.saifuro.com/openapi.yaml — the same endpoints and schemas as these pages, for codegen and API tooling. Where the two disagree, that is a bug — tell us at contact@saifuro.com.