API reference

Gateway API

Model calls, API keys and evidence export. Each endpoint below is read from the gateway's OpenAPI spec. New here? Start with the quickstart.

base https://api.edge.scrutari.aispec 1.0.0-alpha.2openapi.json

Authentication

Send an API key as a bearer token. Each endpoint names the scope the key needs. Create keys in the dashboard or with POST /v1/api_keys.

header
Authorization: Bearer $SCRUTARI_API_KEY

Model calls

Model calls through the gateway. POST /v1/messages and POST /v1/chat/completions are two request formats, Anthropic's and OpenAI's, not two providers: use the one your SDK speaks. The model name picks the provider (OpenAI, Anthropic, Google Gemini or AWS Bedrock), so either format reaches any model the tenant has enabled. GET /v1/models lists those models.

Every call needs the inference:invoke scope, counts against the tenant's token quota and passes the PHI/PII policy. The model runs on a platform route or on the tenant's own provider key.

POST/v1/messagesCall a model in Anthropic's Messages format.

Key scope inference:invoke

Anthropic Messages shape. Returns a JSON message by default, or an SSE text/event-stream of Anthropic Messages events when the request sets stream: true.

Request body (JSON): model (string), max_tokens (integer, required), and messages (a list of {role, content} where role is user or assistant). Optional: a top-level system prompt, temperature, stream, and tools. content may be a plain string or an array of content blocks; images are not supported.

Tool use: send tools (each with name, description and an input_schema JSON Schema object). When the model wants a tool, the response has stop_reason: "tool_use" and tool_use content blocks. Run the tool yourself and send its output as a tool_result block in the next request, with the earlier turns and the same tools. The gateway never executes a tool. Tool arguments and results pass the same PHI/PII policy as message text. Tool requests are not cached, cannot set stream: true, and accept only tool_choice {"type":"auto"}.

Request body

modelstringrequired

Model name, as listed by GET /v1/models.

max_tokensintegerrequired

The most tokens the model may write. Required, as in Anthropic's API.

messagesarray of objectsrequired

Conversation turns. Roles are user and assistant; the system prompt goes in the top-level system field.

2 nested fields
rolestringrequired

user or assistant.

contentstring or array of objectsrequired

A plain string or an array of content blocks.

8 nested fields
typestringrequired

Block type: text, tool_use or tool_result.

textstring

Text payload, present on text blocks.

idstring

Call id, present on tool_use blocks.

namestring

Tool name, present on tool_use blocks.

inputobject

Tool arguments, present on tool_use blocks.

tool_use_idstring

Id of the call being answered, present on tool_result blocks.

contentobject

Tool output on tool_result blocks: a string or text blocks.

is_errorboolean

True when the tool failed, on tool_result blocks.

systemstring or array of objects

Optional top-level system prompt (string or text blocks).

8 nested fields
typestringrequired

Block type: text, tool_use or tool_result.

textstring

Text payload, present on text blocks.

idstring

Call id, present on tool_use blocks.

namestring

Tool name, present on tool_use blocks.

inputobject

Tool arguments, present on tool_use blocks.

tool_use_idstring

Id of the call being answered, present on tool_result blocks.

contentobject

Tool output on tool_result blocks: a string or text blocks.

is_errorboolean

True when the tool failed, on tool_result blocks.

temperaturenumber

Sampling temperature, forwarded as-is to the provider.

streamboolean

Streaming flag. true switches the response to an SSE text/event-stream of Anthropic Messages events.

toolsarray of objects

Tools the model may call. The gateway forwards the definitions and returns the model's tool_use blocks; the caller runs the tools and sends tool_result blocks on its next request. Not supported together with stream: true.

4 nested fields
typestring

Tool kind. Omit it or send "custom"; provider-hosted tools are not supported.

namestringrequired

Name the model uses to call the tool. Unique within a request.

descriptionstring

What the tool does, written for the model.

input_schemaobject

JSON Schema object describing the tool's arguments.

tool_choiceobject

How the model picks a tool. Only {"type": "auto"} (the default when omitted) is supported.

Example

curl
curl https://api.edge.scrutari.ai/v1/messages \
  -H "Authorization: Bearer $SCRUTARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": "Say hello."
      }
    ]
  }'

Responses

200

An Anthropic message object (JSON), or when stream: true a text/event-stream of Messages events (message_start through message_stop).

401

Missing, malformed, or revoked API key.

403

API key lacks the inference:invoke scope, or no upstream provider credential is configured for the resolved model.

404

The requested model is not configured in this tenant's catalog.

422

Invalid request body, an unsupported message role, an invalid or unsupported tool definition or tool block, or PHI/PII detected in the prompt.

429

The tenant's monthly token quota is exhausted, or the upstream provider rate-limited the request.

503

The model catalog, quota backend, credential store, or upstream provider is temporarily unavailable.

POST/v1/chat/completionsCall a model in OpenAI's Chat Completions format.

Key scope inference:invoke

OpenAI-style Chat Completions, text-only. Returns a JSON chat.completion by default, or an SSE text/event-stream of chat.completion.chunk frames when the request sets stream: true.

Request body

OpenAI-style Chat Completions request. Text content only (tools and multimodal parts are not yet supported and are rejected with 422). Set stream: true to receive an SSE text/event-stream of chat.completion.chunk frames terminated by data: [DONE].

modelstringrequired

Model name, as listed by GET /v1/models.

messagesarray of objectsrequired

Conversation messages in order.

2 nested fields
rolestringrequired

system, user or assistant. Other roles are rejected.

contentstring

Text body. Absent/null is treated as empty.

max_tokensinteger

Older name for the output cap. Both names are accepted; max_completion_tokens wins when both are set.

max_completion_tokensinteger

The most tokens the model may write.

temperaturenumber

Sampling temperature; forwarded as-is to the provider.

streamboolean

Streaming flag. true switches the response to an SSE text/event-stream of chat.completion.chunk frames.

Example

curl
curl https://api.edge.scrutari.ai/v1/chat/completions \
  -H "Authorization: Bearer $SCRUTARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": "Say hello."
      }
    ]
  }'

Responses

200

A chat.completion object (JSON), or when stream: true a text/event-stream of chat.completion.chunk frames closed by data: [DONE].

401

Missing, malformed, or revoked API key.

403

API key lacks the inference:invoke scope, or no upstream provider credential is configured for the resolved model.

404

The requested model is not configured in this tenant's catalog.

422

Invalid request body, an unsupported message role, or PHI/PII detected in the prompt.

429

The tenant's monthly token quota is exhausted, or the upstream provider rate-limited the request.

503

The model catalog, quota backend, credential store, or upstream provider is temporarily unavailable.

GET/v1/modelsList available models.

Key scope inference:invoke

The tenant's enabled public model names.

Example

curl
curl https://api.edge.scrutari.ai/v1/models \
  -H "Authorization: Bearer $SCRUTARI_API_KEY"

Responses

200

The tenant's enabled public model names in an OpenAI-style {object: "list", data: [{id, object, owned_by}]} envelope.

401

Missing, malformed, or revoked API key.

403

API key lacks the inference:invoke scope.

503

The model catalog is temporarily unavailable.

API keys

Create, list and revoke API keys. The key itself is returned once, in the POST /v1/api_keys response. Later reads return only its metadata and key_hint. A lost key cannot be recovered; revoke it and create a new one.

POST/v1/api_keysCreate an API key.

Key scope api_keys:write

The response carries the key itself in plaintext, once. Store it right away: later reads return only its metadata and key_hint, and a lost key cannot be recovered.

The new key can hold only scopes the calling key holds. A calling key with * can grant any scope.

Errors you can fix in the request:

  • 422 name_invalid: the name is empty or longer than 100 characters.
  • 422 scope_invalid: a scope is not in the accepted list.
  • 422 environment_invalid: the environment is not live or test.
  • 403 scope_overreach: a requested scope is one the calling key does not hold.

Request body

The key to create. The tenant comes from the calling key, not the body.

namestringrequired

A label for the key, 1 to 100 characters. Use it to tell keys apart by purpose, for example terraform-prod or ci-runner.

scopesarray of stringsrequired

What the key may do. Each scope is a <resource>:<action> pair, and * grants everything. An unknown scope returns 422 scope_invalid. A key can grant only scopes it holds itself.

Accepted values: *, api_keys:read, api_keys:write, routes:read, routes:write, domains:read, domains:write, members:read, members:write, tenants:read, tenants:write, audit_log:read, traces:read, inference:invoke, provider_credentials:write, webhooks:read, webhooks:write, mcp:invoke, zones:read, zones:write, transport_policy:read, transport_policy:write, pii_policy:read, pii_policy:write, memory:read, memory:write, memory:purge.

environmentstring

live (the default) or test. It sets the key prefix: scru_live_ or scru_test_.

Example

curl
curl https://api.edge.scrutari.ai/v1/api_keys \
  -H "Authorization: Bearer $SCRUTARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-runner",
    "scopes": [
      "inference:invoke"
    ]
  }'

Responses

200

The key was created. plaintext carries the key and is returned only in this response.

Response fields
idstring

Key id: ak_ followed by a base32 string. It stays the same for the life of the key, including after revocation.

tenant_idstring

The tenant that owns the key. Taken from the calling key, never from the request body.

namestring

The label from the request.

scopesarray of strings

The scopes granted.

environmentstring

live or test.

key_hintstring

Last 4 characters of the key, for display.

created_atstring

When the key was created, RFC 3339.

plaintextstring

The key itself, in the form scru_(live|test)_<26 characters>. Returned only here, once. Store it; it cannot be read again.

401

Missing, malformed, or revoked API key.

403

API key lacks the api_keys:write scope, or a requested scope is one the calling key does not hold.

422

name, scopes or environment is not valid.

500

Internal error.

GET/v1/api_keysList the tenant's API keys.

Key scope api_keys:read

Returns the tenant's active keys a page at a time. Revoked keys are left out. The key itself is never included, only its metadata and key_hint.

Parameters

cursorstringin query

Opaque pagination cursor from the previous response's next_cursor. Omit on the first page.

limitintegerin query

Page size, 1 to 100. Default 20.

auto_managedbooleanin query

Leave out, or set false, for the keys you created. Set true to list the keys the platform created for its own use instead, such as live trace session keys. One call returns one kind, never both.

Example

curl
curl https://api.edge.scrutari.ai/v1/api_keys \
  -H "Authorization: Bearer $SCRUTARI_API_KEY"

Responses

200

A page of the tenant's active API keys.

Response fields
dataarray of objects

The items on this page.

9 nested fields
idstring

Key id: ak_ followed by a base32 string.

tenant_idstring

The tenant that owns the key.

namestring

The key's label.

scopesarray of strings

The scopes granted.

environmentstring

live or test.

key_hintstring

Last 4 characters of the key, for display.

created_atstring

When the key was created, RFC 3339.

last_used_atstring

When the key was last used, RFC 3339. null if it has never been used. Updated with a short delay.

auto_managedboolean

true for keys the platform creates for its own use, such as the dashboard's live trace session keys. false for keys you create. The list endpoint leaves these out unless called with ?auto_managed=true. They do not count toward the plan's key limit.

has_moreboolean

True when another page follows.

next_cursorstring

Pass this as cursor to get the next page. Absent on the last page.

401

Missing, malformed, or revoked API key.

403

API key lacks the api_keys:read scope.

422

Invalid limit or malformed cursor.

500

Internal error.

GET/v1/api_keys/{id}Read one API key.

Key scope api_keys:read

Returns the key's metadata and key_hint, never the key itself. Revoked and expired keys are returned too, so a client such as a Terraform import sees the key's true state. An id that belongs to another tenant returns 404, the same as an id that does not exist.

Parameters

idstringin pathrequired

Key id from a create or list response.

Example

curl
curl https://api.edge.scrutari.ai/v1/api_keys/ak_01k4r9j7y8x2v3m6q1w5z9b7n2 \
  -H "Authorization: Bearer $SCRUTARI_API_KEY"

Responses

200

The key's metadata, without the key itself.

Response fields
idstring

Key id: ak_ followed by a base32 string.

tenant_idstring

The tenant that owns the key.

namestring

The key's label.

scopesarray of strings

The scopes granted.

environmentstring

live or test.

key_hintstring

Last 4 characters of the key, for display.

created_atstring

When the key was created, RFC 3339.

last_used_atstring

When the key was last used, RFC 3339. null if it has never been used. Updated with a short delay.

auto_managedboolean

true for keys the platform creates for its own use, such as the dashboard's live trace session keys. false for keys you create. The list endpoint leaves these out unless called with ?auto_managed=true. They do not count toward the plan's key limit.

401

Missing, malformed, or revoked API key.

403

API key lacks the api_keys:read scope.

404

No key with this id exists for the authenticated tenant.

500

Internal error.

DELETE/v1/api_keys/{id}Revoke an API key.

Key scope api_keys:write

The revoked key is rejected with 401 from then on and cannot be re-enabled; create a new key instead. The key's record is kept, marked revoked, so audit records can still name it. Revoke a lost key: there is no way to recover it.

Parameters

idstringin pathrequired

Key id: ak_ followed by a base32 string.

Example

curl
curl -X DELETE https://api.edge.scrutari.ai/v1/api_keys/ak_01k4r9j7y8x2v3m6q1w5z9b7n2 \
  -H "Authorization: Bearer $SCRUTARI_API_KEY"

Responses

200

Key revoked.

Response fields
idstring

Id of the revoked key.

revokedboolean

Always true on success.

401

Missing, malformed, or revoked API key.

403

API key lacks the api_keys:write scope.

404

No active key with this id for the authenticated tenant.

422

Path parameter id is not in the ak_ format.

500

Internal error.

Evidence export

Evidence packs for the key's own tenant. POST /v1/compliance_exports queues a build, the export resource reports its status, and the download returns the format v2 pack as JSON Lines: signed records, Merkle inclusion proofs, anchors and public keys. Anyone can verify the pack offline with the open-source scrutari-verify tool. Requires the audit_log:read scope and a plan that includes compliance export.

POST/v1/compliance_exportsQueue a compliance export for the key's tenant.

Key scope audit_log:read

Request body

Optional time window. An empty body exports everything.

fromstring

Inclusive lower bound on record time, RFC 3339. Omit for no lower bound.

tostring

Inclusive upper bound on record time, RFC 3339. Omit for no upper bound.

Example

curl
curl https://api.edge.scrutari.ai/v1/compliance_exports \
  -H "Authorization: Bearer $SCRUTARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-11-15T06:00:00Z",
    "to": "2026-11-15T07:00:00Z"
  }'

Responses

202

Export queued. Poll the export until download_ready is true, then download it.

Response fields
idstring

Export id (UUID).

statusstring

pending, building, ready or failed.

format_versioninteger

Pack format. 2 is the format scrutari-verify checks offline.

audit_rowsinteger

Control-plane audit records in the pack. Null until built.

ai_audit_rowsinteger

AI call records in the pack. Null until built.

anchor_rowsinteger

Anchors in the pack. Null until built.

errorstring

Why the build failed, when status is failed.

created_atstring

When the export was queued, RFC 3339.

ready_atstring

When the pack was built, RFC 3339. Null until built.

expires_atstring

When the pack stops being served.

download_readyboolean

True once the pack is built and not expired.

401

Missing, malformed, or revoked API key.

403

API key lacks the audit_log:read scope, or the tenant's plan does not include compliance export.

409

The tenant already has the maximum number of exports queued or building.

422

from or to is not an RFC 3339 timestamp, or from is later than to.

429

Per-key rate limit for the export routes exceeded, or the tenant has reached its hourly export limit (export_hourly_limit).

500

Internal error.

GET/v1/compliance_exports/{id}Report one export of the key's tenant.

Key scope audit_log:read

Parameters

idstringin pathrequired

Export id (UUID) from the create response.

Example

curl
curl https://api.edge.scrutari.ai/v1/compliance_exports/745fef5a-a0ee-4eec-bc0f-8e91b06c0d13 \
  -H "Authorization: Bearer $SCRUTARI_API_KEY"

Responses

200

The export job.

Response fields
idstring

Export id (UUID).

statusstring

pending, building, ready or failed.

format_versioninteger

Pack format. 2 is the format scrutari-verify checks offline.

audit_rowsinteger

Control-plane audit records in the pack. Null until built.

ai_audit_rowsinteger

AI call records in the pack. Null until built.

anchor_rowsinteger

Anchors in the pack. Null until built.

errorstring

Why the build failed, when status is failed.

created_atstring

When the export was queued, RFC 3339.

ready_atstring

When the pack was built, RFC 3339. Null until built.

expires_atstring

When the pack stops being served.

download_readyboolean

True once the pack is built and not expired.

401

Missing, malformed, or revoked API key.

403

API key lacks the audit_log:read scope, or the tenant's plan does not include compliance export.

404

No export with this id exists for the authenticated tenant.

422

Path parameter id is not a UUID.

429

Per-key rate limit for the export routes exceeded.

500

Internal error.

GET/v1/compliance_exports/{id}/downloadDownload the built pack of one export of the key's tenant.

Key scope audit_log:read

Parameters

idstringin pathrequired

Export id (UUID) from the create response.

Example

curl
curl https://api.edge.scrutari.ai/v1/compliance_exports/745fef5a-a0ee-4eec-bc0f-8e91b06c0d13/download \
  -H "Authorization: Bearer $SCRUTARI_API_KEY" \
  -o pack.jsonl

Responses

200

The format v2 pack as JSON Lines: header, signing keys, records with inclusion proofs, anchors, manifest. Verify it offline with scrutari-verify.

401

Missing, malformed, or revoked API key.

403

API key lacks the audit_log:read scope, or the tenant's plan does not include compliance export.

404

No export with this id exists for the authenticated tenant, or it is not built yet, or it has expired.

422

Path parameter id is not a UUID.

429

Per-key rate limit for the export routes exceeded.

500

Internal error.

Errors

Every error response has the same JSON body, under one error key.

typestring

The error category.

codestring

A stable machine-readable code, for example scope_invalid.

messagestring

What went wrong, in a sentence for people.

paramstring

The request field at fault, when the error is about one field.

request_idstring

Id of the request. Quote it when you contact support.

The error category. Each value maps to one HTTP status: validation_error 422, authentication_error 401, permission_error 403, not_found_error 404, conflict_error 409, rate_limit_error 429, api_error 500, service_unavailable_error 503. Values are not removed within a major version, so clients can decide from this whether to retry.

Not on this page

Routes, domains, members and policies are in the raw spec. The public anchor feed is described on the transparency page.

Questions this page does not answer: partnerships@scrutari.ai