The API behind the dashboard, for your own scripts: the same resources, with a management key.
Overview
Base URL: https://{region}.api.alecturalabs.com/v1, where {region} is us, eu or au.
The OpenAPI 3.1 document this page is built from: openapi.yaml.
The management API serves the dashboard and your scripts. The gateway, which your
servers call, has its own reference.
Hosts
Each region has its own host, and an environment's config and traffic are managed on its
region's host. A key or an environment used on another region's host is refused with 403 wrong_region, naming the right host. The team, its members, projects and environments, in every
region, are managed on us.api.alecturalabs.com, the one place the team directory is written.
Authentication
Every request carries Authorization: Bearer … with one of:
a management key (sk-alectura-mgmt-…), which acts on the environment it belongs to, with
its permissions;
a session: the Stytch session JWT of a team member signed in to the dashboard, which acts
with the member's role on the environment named by the Alectura-Environment header;
a portal session (ps-alectura-…), from POST /portal_sessions, which acts for one
organization's admin on the environment it was made in: only on operations marked
x-alectura-portal with a feature it has, and only on what its organization owns, but for
reading what applies to its requests.
Permission
Allows
send
On a sending key, calling the gateway. On a management key or a role, creating and rotating sending keys, whose secrets call the gateway; a management key never calls the gateway itself
A request's content and attachments; every read is recorded as a request.content_read event
manage
Changing config, suspensions, organizations and users; dispositions; replays, evidence packs and assessments; API keys and webhooks
Roles give a team member permissions: admin has all four and manages the team; developer
has all four; viewer has read. A key never holds more than whoever made it, and its secret,
when it is made or rotated, goes only to a caller who holds every permission the key holds. So
creating or rotating a sending key takes send as well as manage. Each operation names what
it needs in x-alectura-permission, and team operations in x-alectura-role.
Conventions
Every object has an object field naming its type, and an id: a ULID with a prefix for its
type, such as org_01M3PQE5R0….
Times are RFC 3339 in UTC with milliseconds. Money is a decimal string in USD.
Lists take limit (1 to 100, default 10), before or after (an id), and order (desc by
default), and return {"object": "list", "data": […], "list_metadata": {"before", "after"}}.
A POST that creates or changes something takes an Idempotency-Key. A retry with the same
key returns the first result for 24 hours; the same key with a different body is
422 idempotency_key_reused.
PATCH merges: an omitted field is unchanged, null clears a field, and a list is replaced
whole.
An operation that takes no body accepts none, or {}.
Unknown fields and parameters are refused with 422. Responses only ever gain fields, so
clients ignore fields they don't know.
Errors are {"code", "message", "errors", "request_id"}, where errors lists problems with
particular fields.
Organizations and users take your own identifier as external_id, and up to 10
metadata pairs of strings.
Webhooks
Each event goes to every enabled endpoint that subscribes to it, as a POST of the event
object. Order isn't guaranteed; ids and timestamps are.
Alectura-Signature: t=1790680024123, v1=5f1c… signs the delivery: v1 is the hex
HMAC-SHA256, with the endpoint's secret, of the timestamp in milliseconds, a ., and the raw
body. Check it, and that t is within 5 minutes. For 24 hours after a secret is rotated, a
delivery carries a v1 for each secret.
Alectura-Delivery-Id stays the same across retries, so a receiver can drop duplicates.
Any 2xx within 10 seconds is success. Otherwise the delivery is tried again after 1 minute,
10 minutes, 1 hour and 12 hours. After the fifth failure it has failed, and the endpoint is
disabled until you enable it again.
Errors
Every operation can answer with these. The body is an Error, with a code to branch on and the request_id to quote to us.
An error. 400 invalid_request: the body can't be parsed. 401 unauthenticated, with WWW-Authenticate. 403 permission_denied or wrong_region, which a key's type and region decide before it is looked up, so a sending key or another region's key gets 403 even when expired or revoked. 404 not_found. 405 method_not_allowed, with Allow. 409 conflict: the object's state doesn't allow the change. 410 gone: the content or files have passed their retention. 422 validation_failed, with errors, or idempotency_key_reused or connection_test_failed. 429 rate_limited, with Retry-After, the seconds until the next request passes: each team may make a burst of 100 requests, refilling at 25 a second, whichever key or member makes them.
503 unavailable: a store or service the API depends on failed. Retrying may help; send the same Idempotency-Key so a write that did commit isn't made twice. 500 internal_error: a fault in the API itself, such as a stored object that can't be read; it is logged. A retry rarely helps, so quote the request_id to us.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Destroys the organization's key at once, which makes its content, attachments and pseudonyms unreadable, then a job removes the rest. Its key leaves backups within 7 days. Records keep a keyed hash in place of its id.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Each change makes a new version. The body merges like every PATCH, settings included, except match: when given, it replaces the whole match, so send every field the policy should still match on. A merge would read a null in it as "clear this field" and widen the policy to requests it never matched.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The effective policy for an identityPermission: read
Combines every policy that matches the identity, as the gateway would for a request carrying these values in its Alectura-* headers. An omitted parameter means the header is absent. In a portal session, the identity is the session's organization on the plan its latest request named, leaving out policies that match by user or tags, and another organization, user, plan, tags and model are refused. It names only the organization's own policies and connections, and shows routing.connections only in trace.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Preview a draft's effect on effective policiesPermission: read
Each identity's effective policy, as GET /effective_policy gives it, before and after a draft, except that an organization with no plan given has the plan its latest request named: with the policies as saved, and with the draft in place of the policy it changes or added as a new policy. Both come from one read of the policies, so a difference is the draft's alone. Nothing is saved, and no job is queued. A new draft has an id that no saved policy has, and after names it as the source of what it decides. In a portal session, the draft changes a policy the organization owns, or is a new one it owns, matching only it and refused where a save would be; each identity is the session's organization, with no userplan or tags; and each side is as GET /effective_policy shows it there.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Update, activate or disable a connectionPermission: manage
Setting state to active runs the connection's test first, and fails with 422 connection_test_failed, listing the failed checks, unless every check passes. Replacing the credential of an active connection tests the new one the same way before it is used.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Sends a small request for each of the connection's models, in each format family its provider serves the model in, and checks the answers, without changing the connection's state.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Sets where the environment's team-held content goes, replacing the store it had. A new store, or one whose bucket, region, prefix or role changed, is a draft, and takes no content until its test passes. The environment's external id stays the same across changes. The bucket's region must be in the environment's own region, such as eu-central-1 for an eu environment; any other is refused with 422 validation_failed, code outside_region.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
From now on, content kept under team retention is kept nowhere. What the store holds stays there, yours to keep or delete; Alectura reads none of it any more.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
Assumes the store's role with the environment's external id, then writes, reads and deletes {prefix}{environment}/alectura-test in its bucket. When that works, the store becomes active.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The response is the only time the secret is shown. A retry with the same Idempotency-Key returns the key without its secret; rotate it to get a new one. The caller must hold each permission the key gets, send for a sending key, or it is refused with 403 permission_denied. A sending key is answered after the gateways' next read of it, about 7 seconds on.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Gives the key a new secret. The old secret keeps working for the grace period, so servers can move over without downtime. A sending key's new secret is answered after the gateways' next read of it, about 7 seconds on; an old one given no grace period stops working within 10 seconds, as a revoked key does. The caller must hold each permission the key holds, send for a sending key, or it is refused with 403 permission_denied.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
Half an hour in which one of your organizations' admins manages its own policies and connections, in a page you show inside your product.
POST/portal_sessions
Create a portal sessionPermission: manage
A page where the organization's admin lists, creates, edits and deletes the policies and connections the organization owns, and nothing else, for 30 minutes. Show url in an iframe on an HTTPS page (or http://localhost or http://127.0.0.1 while you try it), or link to it; make a new session each time you show it. Nothing is stored, so it takes no Idempotency-Key: a retry makes another session. A session ends early when the key or member that made it can no longer manage, or when the organization is deleted. Its requests count against a rate limit of the organization's own, not the team's.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Get one version of a request's contentPermission: read_content
Rebuilds the version byte for byte, except that each detected secret is replaced by its kind and keyed hash, [secret:kind:hash]. An attachment is referenced by its hash, and fetched with the attachments endpoint. Every read is recorded as a request.content_read event.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
For a streamed response: raw is the stream as it arrived, in server-sent events or, for Bedrock, AWS's event stream; events is newline-delimited JSON, one event per line with the milliseconds since the request began; assembled is the response as one JSON object, as if it hadn't been streamed.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
Totals from rollups and from the query engine, minutes behind.
GET/summary
Totals for the environment, for one organization, or for one userPermission: read
A user's totals are kept by the day, so user_id takes interval=day only, and can't be given with organization_id. A portal session reads only its organization's totals, and can't give user_id.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Each connection's attempts, by period, and healthPermission: read
Each connection the environment's requests tried in the window's hours, by its id, with its attempts in each period of interval. A series' first point counts its whole period, so it can include hours before from; the other counts start at from's hour. A request's attempts each count for their own connection, so one that fell back counts for both. A connection's name, provider and owner, which sets an organization's own apart, are in listConnections.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Totals and series of the environment's requests, filtered and groupedPermission: read
At most 10 minutes behind the gateway: complete_before says how far the answer is complete. A query that reads more than 1 GB is stopped and refused with 422 query_too_large. Each environment runs at most 2 queries at once; a third waits up to 10 seconds, then gets 429 rate_limited. Each team reads at most 5 GB a day, and the region's teams together 20 GB, counted as Athena bills them, and past that gets 429 query_budget until 00:00 UTC. A query counts as 1 GB while it runs, and while the queries running could read the rest of the day's budget, another gets 429 rate_limited. A deploy starts the day's counts again. A query that takes more than 30 seconds is stopped with 503 unavailable. A query refused as too large, stopped at 30 seconds, or whose client disconnects before the answer counts as 1 GB for the day; one that fails for another reason counts nothing. For a list of the requests behind a value, send the same filter to GET /requests.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Declare a system prompt as the app's ownPermission: manage
The usual system prompts are learned from traffic; a declared one is usual from the start, so a user whose requests lack every usual prompt gets the system_prompt_stripped signal. The text is fingerprinted with the environment's key and not kept. A request's system prompt matches when its text is exactly the same, its system blocks joined by line breaks; declaring the same text again is a conflict.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
A connection's alert is raised once, as an alert.raised event, and cleared once, as alert.cleared, after 10 minutes without it; it goes to the webhooks that subscribe to them. One that is off is not raised, and one raised already still clears. limit_threshold turns limit.threshold_crossed on or off.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Replays, evidence packs and assessments, which run in the background.
POST/replays
Replay a draft policy against past requestsPermission: manage
Evaluates the draft against stored requests in the window and reports what would have changed. Requests without retained content replay their routing and uninspected settings only, and uninspected only for attachments: a record can't tell a part the gateway doesn't know from one with no text.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
The environment a session acts on. Required with a session; with a management key or a portal session, it may be sent only if it names its own environment.
Stytch emails a sign-in link. The invited member holds the role once they sign in.
Parameters
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
The environment lives in its region for good. Its region's host serves its config and traffic, and sets up its state there on first use, starting with a baseline policy that matches every request and allows its own region, then global.
Parameters
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
What a team member tells Alectura with the dashboard's feedback button, and the errors the dashboard shows, on us.api only. Sessions only.
POST/feedback
Send feedback
Keeps what a team member tells Alectura about the dashboard: a message, a recording, or both, with a screenshot of the page they were on. The feedback is kept as soon as it is sent, in one bucket in the US whatever the region of the page, and each file it names then goes to its own upload URL. A URL takes one PUT of the file, with the type and size declared here, for an hour.
Parameters
Idempotency-Keyheader
string
Makes a retry return the first result for 24 hours, marked Idempotent-Replayed: true. A body with the same fields in another order is the same request; the same key with a different body is refused with 422 idempotency_key_reused.
Tells Alectura that the dashboard showed an error that Alectura caused: an answer it couldn't read, or a page that failed as it rendered. The report names the page's route and the call, never an id, a message or content, and is logged, not stored, so it takes no Idempotency-Key.
The user's open signals, strongest first: those neither dismissed nor acted on. The management API's users carry them; a user in an event's data doesn't.
An organization's policy matches only that organization, sets nothing looser than its default, and is what its admin manages in a portal session. It never changes.
Default the environment. An organization's policy must match that organization's external_id. A setting looser than its default, which applies when no policy sets it, is refused (looser), and so is abuse, whose suspensions reach past the organization. The team's own policies still apply to the organization, and where both set something the stricter wins, so its policy only tightens what applies. In a portal session, it is always the session's organization, and a change to a setting outside the session's setting_groups, or to the match of a policy that sets one, is refused (not_permitted). An organization owns at most 20 policies and 5 connections, and all of an environment's organizations 1,000 policies (too_many).
Selects by Alectura-Tags, by key in lowercase: each key given holds as the fields above do, with up to 20 values, and null holds for a request without that key. Values match exactly. The policy's limits count only the requests its tags select, and a policy with tags can't set abuse, since a suspension stops all of a user's requests.
Example
{"organization": "globex"}
MatchValue
A value, any of a list of values, or null for requests that don't send the header.
Each setting combines across matching policies by the rule in its description. Every rule only tightens, except routing's add, which can widen where a request may go. A setting no matching policy sets takes its default. An older spelling is still read, where a property says so.
What to do with content in a request that nothing can inspect, such as images or a part the gateway doesn't know. Signed or encrypted content passes, since the provider checks it. block wins, refusing the request with attachment_uninspectable. Default allow, with the content recorded as uninspected. It acts on requests only: what an answer carries that nothing reads passes, and is recorded in coverage.
"allow" | "block"
AbuseSettings
What happens when a signal flags a user for abuse.
suspend_at
number
Suspend the user for 24 hours when a signal's score, of any kind Signal.kind lists, reaches this; a team member can lift it sooner, or suspend by hand for longer. It suspends users only: no policy suspends an organization, so organization.suspended comes only from a team member or a key. The lowest wins. Default: never.
Example
{"suspend_at": 0.9}
RoutingSettings
Routing's keys are allow-lists. A request seeds each, ranked 0: its model, the environment's region and its organization's own active connections, never another organization's; and the environment's active connections, unnumbered. Each matching policy may add members, keep only some, or remove some, and what's left is ((seed ∪ adds) ∩ onlys) − removes. Across policies adds union, each member at its lowest rank, onlys intersect and removes union, so no policy's add undoes another's only or remove. A request tries connections by their region's rank, then their own, ties at random, so the organization's own go first in their region. The older spelling, a list per key, is still read: as its only, a regions list also as adds ranked in its order, and a connections list as nothing.
Which connections may serve a request, by id. Each id new to the policy must name one of the environment's connections, and in an organization's policy, one the environment owns or that organization's own; any other is refused (not_found), since no request the policy matches could use it. Ids the policy already holds stay, so deleting a connection doesn't block edits.
The models a request may use; an id without a date covers every dated version. The request's own must be left, or it's refused model_not_allowed. The models add names are its fallbacks, by rank, lowest first, then those without one: the gateway tries them after the connections serving its own model, or first while its own cools down on every one, with at least the last of its three attempts. A fallback goes by the id its connection knows it by, which every policy's only and remove must allow, and only in the request's format; under a spend limit, only a model with a list price. Each model goes once, so one naming the request's own model or another fallback again is left out. A limit reserves at the price of the request's own model and settles at the price of the model that answered, at which its cost is too.
data_terms
object
The data terms a connection must declare (Connection.data_terms) to serve a request. A connection whose terms are undeclared doesn't meet a requirement. When no connection that meets them serves the model, the request is refused with no_allowed_connection. Default: any terms.
Fields
retention
"any" | "zero"
zero: only connections whose provider keeps nothing it's sent. Across policies, zero wins. Content retention none doesn't imply it.
training
"any" | "no"
no: only connections whose provider doesn't train on what it's sent. Across policies, no wins.
Where an added member is tried: numbered ones lowest first, then unnumbered ones, {}. An object, so that a merge patch's null can take the member out of add.
rank
integer | null
RetentionSettings
content
"none" | "team" | "7d" | "30d" | "90d" | "365d"
How long a request's content is kept. Across policies, the earliest in this list. Default none. team means held by you rather than by Alectura: in the environment's content store (/content_store), for as long as you keep it. Until the environment has an active content store, team keeps no content, as none. Records are kept 400 days whatever this says.
LimitSettings
For each per, period, action and tags counted, the lowest amount among matching policies wins; limits that differ in any of these all apply. requests and tokens take a minute or a day, and spend a day, a week or a month. A block limit over a minute refuses with 429; over a day, week or month, with 402. A warn limit, above 0, refuses nothing: limit.threshold_crossed reports 80%, 95% and 100% of it. A limit counts the requests whose tags its policy's match selects, all of them when it names none; in the effective policy, each limit shows those as tags. Periods are calendar periods in UTC, and weeks start on Monday.
max_output_tokens
integer
Lowers a request's maximum output to this, and sets it when the request doesn't. The lowest wins.
What a limit does once use reaches it: block refuses the request that would pass it, and warn refuses nothing and only reports. Default block.
"warn" | "block"
LimitTags
Only in the effective policy, events and refusals: the tags of the requests a limit counts, as its policy's match names them. A policy names them in its match, not here.
A request without a user or organization isn't counted against limits for it.
"user" | "organization"
GuardrailSettings
Across policies, a finding takes the strictest action, in the order listed for each, of the matching policies whose guardrail inspects its part, looks for its kind and doesn't exclude its value; warn records it and changes nothing. A guardrail no matching policy sets doesn't run. Older spellings are still read: record and flag as warn, and a mode beside the action, whose monitor makes it warn.
Each guardrail's settings from the matching policies, in their order, less any another is at least as strict as: whose action is as strict and that inspects every part and kind it does, excluding no value it doesn't.
Credentials and private keys. In the request, redact replaces each with [redacted:kind] and block refuses it with blocked_by_guardrail. In the answer (output), streamed or not, redact redacts the same way, holding back the text a secret could still be growing into across deltas, and block cuts the answer with cut_by_guardrail.
Personal data of the kinds selected. In the request, pseudonymize replaces each value with a pseudonym, [[kind:hash8]], which the answer gets back as the value; redact replaces it with [redacted:kind]; block refuses the request. A value found in a message is replaced also where it stands again in that message and the messages after it, and so is a given name or a surname of a person's name that stands alone; a message keeps the text the provider received for it. A request that carries pseudonyms, or continues a stored response, gets a note after its system prompt, or as its system prompt, that tells the model to use them as the values; a Gemini request with cachedContent, and a Responses request with a stored prompt and no instructions, get none. The answer gets each value back also from the forms models write a pseudonym in: its hash alone, single brackets, its kind alone where one value has that kind, and spelled backwards, which gives the value spelled backwards. In the answer (output), redact redacts what the answer holds and block cuts it with cut_by_guardrail; under pseudonymize the answer's pseudonyms are restored and personal data the answer adds is recorded, since a pseudonym would reach the client in its place. Signed text, such as a Gemini function call's args, keeps its pseudonyms. person_name, street_address and date_of_birth are found in English text without a model, as accurately as the guardrails docs measure. passport_number, driver_license_number and bank_account_number are numbers that the words before them name, in English, German, Dutch, French, Spanish, Swedish and Italian. A routing number or a sort code names a bank's branch and isn't one, but the account number beside it is. national_id also covers ids that those words name, and other countries' ids that carry a check.
Default all. card_number covers the published test card numbers exclude_test_cards lists, found as test_card_number unless it is set.
exclusions
string[]
Exact values never treated as personal data, such as your support address.
exclude_test_cards
boolean
Never treat these published test card numbers as personal data, however they're spaced: 4242424242424242, 4000056655665556, 4111111111111111, 5555555555554444, 2223003122003222, 5200828282828210, 5105105105105100, 378282246310005, 371449635398431, 6011111111111117, 6011000990139424, 3056930009020004, 36227206271667, 3566002020360505 and 6200000000000005. Each is a number payment providers publish for a test payment that succeeds; their declining and 3-D Secure test cards, such as 4000 0000 0000 0002, are still found as card_number. The list changes only with this contract. Default false.
tier
"local" | "ner"
local, the default: the gateway's own detectors. ner also asks Alectura's NER model, GLiNER multi-PII v1, for person names in the blocks of the parts it selects, on a host in the request's region that sends no text out. Each name it finds is a person_name value, which takes the strictest action of the settings that look for names there, so kinds includes person_name. The provider call waits for it: a request asks about the blocks the gateway's scan cache doesn't hold, newest first, up to 4 KB, and waits at most 1 second plus 1.7 seconds for each KB asked. Older blocks and a PDF's text layer keep the gateway's own findings. The scan cache is per gateway task and starts empty after each deploy and policy change, so the next turn of a conversation asks again about its newest 4 KB, and a name that only the NER model found in an older turn then goes to the provider as written. A check that fails, has no answer in that time, or finds the NER host busy with other requests, leaves the gateway's findings. Each block's check is in the request's checks. A region runs the NER host once a team asks for it with the dashboard's Feedback button; elsewhere the API refuses the setting with tier_unavailable.
InjectionGuardrail
Instructions that try to take over the model, in the request's parts, tool results included. It judges the request, not the answer, so its parts can't name output. Unset, its parts leave out system: your own system prompt says what to answer and what never to share, as an attack does. If you put fetched documents or your users' text in the system prompt, name system, or that text is not read.
local, the default: the gateway's own detector. model also asks a model about each block of the parts it selects, through one of your own connections, at the same time as the provider call, never an organization's. The models, in order, are Gemini 3.1 Flash-Lite, Claude Haiku 4.5 and gpt-5-nano, through the first connection that serves one where the request may go: its regions, data terms and connections apply. decision asks a decision model in the same way, as one choice between a prompt injection, a request and other content. The models, in order, are TypeSafe's Jev 1.14, through OpenRouter's Decisions API on an OpenRouter connection that lists typesafe/jev-1.14, or a snapshot such as typesafe/jev-1.14-20261014, which a new one doesn't replace, and GPT-6 Luna, through OpenAI's Decisions API on an OpenAI connection that lists gpt-6-luna. OpenRouter's main host promises no region, so Jev needs global in the request's regions, or OpenRouter's Business plan for its EU or US host. A model that fails or can't answer leaves the question to the next. A probability of 0.5 or more for a prompt injection flags the block. A setting at one of these tiers doesn't cover a setting at the other, so both can ask. A model's finding has kind flagged_by_model and takes the strictest action of the settings that inspect its part. A check that fails, or has no answer in 2 seconds, leaves the gateway's verdict. Each check is in the request's checks, and your provider bills it, outside the request's cost and your limits. A request asks at most 8 questions of up to 4,000 bytes each, its newest text first, so a longer block is asked in parts that overlap by 400 bytes, and a part answered before isn't asked again. Text left out, which the next request asks, and a PDF whose file the gateway rewrote for the provider keep the gateway's verdict and have a not_asked check. The answer's end waits for the checks, as for the gateway's own, and with cut a streamed answer's first text waits too.
IllegalContentGuardrail
Requests for help with a crime, judged by a local model over the parts selected, tool results included. block refuses the request before the provider sees it, with blocked_by_guardrail; warn records the finding and lets it through. The kinds are MLCommons' hazard categories that are crimes wherever the request comes from, with illegal conventional weapons joined to chemical, biological, radiological, nuclear and explosive ones in weapons. It judges the request before the provider sees it, not the answer, so its parts can't name output. Its measured precision and recall per kind are published; start with warn.
local, the default: the gateway's own detector. model also asks gpt-oss-safeguard 120B about each block of the parts it selects, for every kind at once, through one of your own Bedrock connections whose models include openai.gpt-oss-safeguard-120b, where the request may go. decision asks GPT-6 Luna in the same way, through OpenAI's Decisions API on an OpenAI connection that lists gpt-6-luna, as one choice between a request for help with a crime and anything else; a probability of 0.5 or more for a crime flags the block. With either, leave out kinds. Under block, the provider call waits for the answer, and a finding refuses the request with blocked_by_guardrail before the provider sees it. Under warn, the provider call doesn't wait, and the answer's end does. A model's finding has kind flagged_by_model and takes the strictest action of the settings that inspect its part and look for every kind. Its questions, their limits, their records and their billing are as for prompt_injection's tier.
ModerationGuardrail
Hate, harassment, self-harm, sexual content and violence, judged by a local model over the parts selected, tool results and the answer included. The kinds are OpenAI's moderation categories, less illicit content and sexual content with minors, which illegal_content judges. In the request, block refuses it before the provider sees it, with blocked_by_guardrail. In the answer (output), nothing is held back: the model judges each 64 words of a stream after they reach the client, with the 64 before them, and block cuts the answer with cut_by_guardrail at the first finding, up to 64 words after the passage it found. It refuses an answer that isn't streamed. warn records the finding and changes nothing. Its measured precision and recall per kind are published; start with warn.
local, the default: the gateway's own detector. model also asks gpt-oss-safeguard 120B about each block of the request's parts it selects, for every kind at once, at the same time as the provider call, through one of your own Bedrock connections whose models include openai.gpt-oss-safeguard-120b, where the request may go. decision asks GPT-6 Luna in the same way, through OpenAI's Decisions API on an OpenAI connection that lists gpt-6-luna, as one choice between harmful content, a discussion of its topics and other text; a probability of 0.5 or more for harmful content flags the block. With either, leave out kinds. The answer (output) keeps the gateway's own detector. Under block, the answer waits for the model, and a finding cuts it with cut_by_guardrail before any of it goes out. Under warn, the answer's end waits. A model's finding has kind flagged_by_model and takes the strictest action of the settings that inspect its part and look for every kind. Its questions, their limits, their records and their billing are as for prompt_injection's tier.
CustomPatternsGuardrail
Your own regular expressions and word lists. In the request, redact replaces each match with [redacted:name], the name of the pattern that matched, and block refuses the request with blocked_by_guardrail; a match in an attached file's text blocks under either, since a file can't be redacted. In the answer (output), streamed or not, redact redacts the same way, holding back the text a match could still grow into (at most 256 bytes), and block cuts the answer with cut_by_guardrail. In a request or a whole answer, a match longer than 512 bytes is redacted only in part where a shorter branch of the same regex matches inside it. A finding's kind is the pattern's name: a block records one finding for each name, and the answer one for each name and action. redact reads at most one match for each 8 bytes of a block, or of a delta and the text held with it, and 1,000 at least; past that it refuses the request or cuts the answer. Under any action, word lists that match more than 4 times for each byte of the text, as nested words do in a run of one letter, refuse the request or cut the answer too. Each policy's patterns take its action in its parts; where two policies' patterns match the same text, the stricter action wins. The patterns read the text folded as the other guardrails read it, so look-alike and full-width characters, and runs of spaces in a phrase, don't hide a match.
At most 30 regexes, which compile to at most 128 KiB together, and 10,000 words in all the lists.
CustomPattern
namerequired
string
The kind of its findings, and the label of its redactions. Unique in a policy.
regex
string
Rust's regex syntax, as RE2's: no look-around or back-references, so a match takes time linear in the text. It is ASCII, with ASCII \w, \d, \b and (?i), and no (?u): it reads text with look-alike characters folded to ASCII, so words in other scripts go in words. A regex that can match empty text, or compiles past 128 KiB, is refused.
words
string[]
Words or phrases, each matched whole, with ASCII case ignored; a phrase's words match with one space between them.
SystemPromptLeakGuardrail
An answer that repeats the request's system prompt, in its words or close to them. A local model reads the answer, tool calls included, against the system part of the same request, every 8 words of a stream; cut ends the stream with cut_by_guardrail, or refuses a response not yet sent, and warn records the finding. It reads only the answer, so it has no parts. A request without a system prompt has nothing to leak. Start with warn: an answer that follows the prompt closely can look like a leak.
actionrequired
"warn" | "cut"
ToolCallsGuardrail
The tools the answer may call, and what their arguments may say. A call is a finding, tool_not_allowed, when denied names its tool or allowed is set and no entry names it; and argument_not_allowed when no entry that names it has a schema its arguments match. cut stops the answer with cut_by_guardrail before the client gets the call; warn records it. Each call is judged as the client gets it, pseudonyms restored and secrets redacted. A call is judged where the answer names its tool, unless an entry checks its arguments: then, under cut, the stream holds back that call and what follows it until the answer ends, and cuts the answer if that passes 1 MiB. A built-in tool is named by its type, such as web_search or local_shell, and a tool on an MCP server the provider calls as mcp__<server>__<tool>. A tool the provider runs itself has run by the time the answer names it, so nothing is held back for it, and a cut stops only the answer. Set allowed, denied or both; a setting's schemas take at most 32 KiB, with at most 16 patterns. The settings of the team's own policies take at most 256 KiB and 64 patterns in all, those of all organizations' as many, and one organization's 64 KiB and 16 (too_many).
A JSON Schema, draft 2020-12, that the call's arguments must match, as you describe the tool's parameters to a model. Unset: any arguments. A pattern matches anywhere in a string unless it starts with ^ and ends with $, and runs in linear time, so it can't look ahead or behind. A schema can't refer to one outside itself. Set type at each level: without it, a value of another type matches, such as a list in place of one address. A custom tool's free-form input is matched as a string; arguments that aren't JSON, or that name a member twice, match no schema.
ToolName
A tool's name, or a glob in which each * stands for any run of characters, such as mcp__github__*.
string
GroundingGuardrail
Whether the answer says only what its sources support. The sources are what you and your user gave the model: the system prompt, the user's messages and tool results, with the text of their PDFs. The model's own earlier turns and tool calls are not sources. Each sentence of the answer's text is judged against them by a local model as it ends; tool calls, reasoning and closed code blocks aren't judged. A finding has the kind unsupported_claim. warn records it and changes nothing; an action that stops the answer waits for a detector precise enough to stop few good answers. A request with no such text isn't judged. It inspects only output, so it takes no parts. Turn it on for requests whose answers must come from their sources, as in retrieval: an answer from the model's own knowledge is unsupported. Its measured accuracy is published.
actionrequired
"warn"
GuardrailMode
Read, never written: monitor makes the action warn, and enforce keeps it. A patch giving a mode without the action is refused.
"monitor" | "enforce"
Parts
The parts of a request a guardrail inspects. Default all of them that the guardrail reads, except system for prompt_injection. Only secrets, personal_data, moderation and custom_patterns read output; a policy that names it for another guardrail is refused with 422 validation_failed. tool_calls reads only the answer's calls, and has no parts.
The settings as they apply. One no matching policy sets shows at its default: routing to the regions that apply, retention none and uninspected: allow; a guardrail or a limit no policy sets is absent, since its default is to do nothing.
For each setting, by its dotted path, the policies that decided its value. A setting that no policy sets is absent, and takes its default.
decided_by_team
string[]
Only in a portal session: the settings, by dotted path, that the team's policies decide, alone or with the organization's own.
tracerequired
object
How each routing key got its value, by its dotted path: what the request seeds it with, each matching policy's add, only and remove, in id order, and what's left. The seed is the environment's region, every active connection the organization may use, its own ranked 0, and given model, that model; without it, routing.models has no result.
Given model, the connections a request for it would try, in order, whatever their cooldowns: those serving the model, then those serving each fallback. Those of equal ranks share a position, and the gateway orders them at random for each request; it tries at most three, the last for a fallback if there is one.
bedrock_mantle is Bedrock's OpenAI-compatible endpoint in an AWS region, bedrock-mantle, in OpenAI's formats, by its own ids, such as openai.gpt-6-sol and qwen.qwen3-32b: OpenAI's GPT models and the open-weight models Bedrock runs, with a project for each connection. It processes in aws_region, with no cross-region inference, and its role needs bedrock-mantle:CreateInference. gemini is the Gemini API, in its own format. azure is Azure OpenAI, in OpenAI's formats, by its deployments' names. vertex_ai is Vertex AI, in Gemini's format for Google's models and Anthropic's for Claude, by Vertex AI's ids, such as claude-sonnet-4-5@20250929. openrouter is OpenRouter, in OpenAI's formats and Anthropic's, for the models of many providers: by OpenRouter's own ids, such as meta-llama/llama-3.3-70b-instruct, or by the makers' own, such as gpt-5-mini. Its ids for Claude write the version with a dot, as claude-haiku-4.5 does. An id that the price list has no row for, such as openai/gpt-oss-120b, takes the median price of the hosts that list the model. An id that no host lists, or a variant such as openai/gpt-oss-120b:nitro, has no list price, so a spend limit refuses it. Its EU and US base URLs serve only a Business or Enterprise plan, and fail a request that no provider in the region serves. vercel_ai_gateway is Vercel AI Gateway, in OpenAI's formats and Anthropic's, for the models of many providers, by Vercel's ids, such as zai/glm-4.6, priced as OpenRouter's are. It promises no region, since Vercel can handle a request in any region on its way to the provider. Because the gateway refuses providerOptions, set zero data retention and your own provider keys in Vercel's dashboard, and make the connection's data_terms match. simulator answers inside the gateway with recorded responses, in the region of the environment's cell, so no provider is reached or paid: any team may connect it to try Alectura, and outside the demo team each environment may send it a burst of 20 requests and 60 a minute, past which a request no other connection can serve is refused 429 rate_limited.
Only an active connection routes. A connection is activated only after its test passes.
"draft" | "active" | "disabled"
DataTerms
What the provider's terms for this account say, as declared by whoever made the connection. Undeclared counts as retaining. Prompt caching in memory isn't retention.
retentionrequired
"undeclared" | "zero" | "retains"
trainingrequired
"undeclared" | "no" | "yes"
Credential
Write-only. Reading a connection returns only its CredentialHint, or null.
object | object | object
CredentialHint
typerequired
"api_key" | "aws_role" | "google_service_account"
hintrequired
string
The last four characters of a key, a role's name, or a service account's email.
For OpenAI, Anthropic, Gemini, OpenRouter and Vercel AI Gateway. OpenAI's us. host processes requests in the US; its au. host keeps your data at rest in Australia but may process requests elsewhere, so its region is global.
aws_regionrequired
string | null
For Bedrock and Bedrock mantle.
inference_profilerequired
"us" | "eu" | "apac" | "au" | "global" | null
For Bedrock, a cross-region inference profile, or null for the region's own endpoint. For Azure OpenAI, where its deployments process, which you declare and nothing checks; global for Global deployments, else the area of azure_region, such as eu for swedencentral, as Standard and Data Zone deployments process in it.
azure_resourcerequired
string | null
For Azure OpenAI, the resource whose endpoint is https://{azure_resource}.openai.azure.com.
azure_regionrequired
string | null
For Azure OpenAI, the resource's region.
vertex_projectrequired
string | null
For Vertex AI, the Google Cloud project's id.
vertex_locationrequired
string | null
For Vertex AI, where the project's models run, global, us, eu or a region.
openai_projectrequired
string | null
For Bedrock mantle, the project its requests are made in, or null for your AWS account's default project.
Where the endpoint promises to process requests. Derived, never set.
modelsrequired
string[]
The models it serves, by the ids clients send. On Bedrock mantle, by mantle's own ids, such as openai.gpt-oss-120b, which are not Bedrock runtime's. On Bedrock, each id must be processed in the connection's region, or the request is refused with a validation error on models; an inference profile's id, such as eu.…, runs in that profile's area, and any other in aws_region.
Unique among its owner's connections, ignoring case: the environment's, or one organization's. A name another has fails with 422 validation_failed, code taken.
For Bedrock mantle: a project in your AWS account, sent with each request as OpenAI-Project. Bedrock tags the project's usage for cost allocation and keeps its stored responses apart. Give each organization that needs its own project its own connection. Default your account's default project.
For Bedrock, and the simulator, which stands in for it: the application inference profile that the connection calls each of its models through, by the model's id in models, so Bedrock tags the usage as the profile says. A client may send the profile's ARN in place of the model id; the gateway reads it as that model, for policies, limits, routing and records. Bedrock then bills the profile of the connection that serves the request, which may be another than the ARN sent: give each organization that needs its own profile its own connection, which routing prefers, or rank the connections in a policy. A profile is in the connection's aws_region, and copies one model. The connection's test reads each profile, which needs bedrock:GetInferenceProfile, and fails unless the profile calls that model, in AWS regions within the connection's region. A new profile on an active connection is tested before the change is kept. Default {}.
What was checked, such as credential, model:gpt-5, profile: and a model id, stream or usage.
passedrequired
boolean
reasonrequired
string | null
Why it failed, such as invalid_credential, model_unavailable, invalid_stream, missing_usage, profile_unreadable, profile_mismatch or region_not_allowed.
Where team-held content goes: an S3 bucket in your own AWS account, reached through a role there whose trust policy allows Alectura's account with external_id. Content packs, attachments and pseudonyms are written under prefix, sealed with each organization's key, and read through the same role. Their lifecycle is the bucket's.
objectrequired
"content_store"
bucketrequired
string
regionrequired
string
prefixrequired
string
What every key starts with: empty, or ending in /.
role_arnrequired
string
external_idrequired
string
What the role's trust policy must require as sts:ExternalId.
staterequired
"draft" | "active"
Only an active store takes content. A store becomes active when its test passes.
What a portal session reaches, of what its organization owns: policies also reads its organization's totals.
"policies" | "connections"
PortalSettingGroup
A group of policy settings, as the portal shows them. connections is a policy's routing.connections; the organization's own connections, which the connections feature manages, go first whatever it says (R51). guardrails is each guardrail's settings but its tier, and model_tier is the tiers: the checks of tier: model and tier: decision go through your connections, which you pay for, and those of personal data's tier: ner go to Alectura's NER host in the region.
The groups of policy settings the organization's admin may change; it reads the rest, and a change to one, or to the match of a policy that sets one, is refused with not_permitted. Only with policies. Default: every group but model_tier. Within a group, the admin sets nothing looser than your policies give it.
blocked: no provider got the request, refused by a policy or a suspension, or as one the gateway can't serve, such as invalid_request or unsupported_endpoint; the record's refusal says which, and request.blocked fires only for a policy's. cut: the provider got it and a guardrail stopped the answer.
Null for a request refused before its path named an endpoint.
modelrequired
string | null
The model the request asked for, in its path or body; null when it named none that could be read. A request refused before its policies resolved keeps this, and its valid identity headers, too. A fallback that answered it is in attempts, and cost is at its price.
streamrequired
boolean
statusrequired
integer | null
The HTTP status the client received; null while pending.
The connection the request last reached, if it reached one, whether it answered, failed or was cancelled; its attempts say which. An attempt reached its connection unless it is provider_unreachable; one provider_disconnected was sent and broke off.
The provider's HTTP status; null if it never answered.
errorrequired
string | null
Why the attempt failed, such as provider_timeout, provider_disconnected (the connection broke once the request was out), cancelled (a guardrail cut the request before an answer came) or the provider's own error code.
For each block, the detectors that ran on it, or why none did. A request a provider answered has one more entry, part output, for the answer: read by the guardrails that select output, or not_selected. Findings in the answer name that entry's block. What in the answer nothing reads, such as an image or encrypted content, follows it in entries of its own.
Why no detector ran, or null when one did. images_uninspected, audio_uninspected and video_uninspected: no detector reads that modality. files_uninspected: a file with no text layer a detector reads, or one the body only points at. uninspectable: a part the gateway doesn't read. encrypted: signed or encrypted provider content, which passes through byte for byte. not_selected: no guardrail that runs selects the block's part, or the only one that would read the answer is grounding and the request has no sources. refused_first: the request was refused, by a suspension, a limit or another guardrail, before a guardrail that would have read the block ran.
Each question a guardrail's model tier asked about a block, in the order asked, then each block it didn't ask about whole; under personal data's tier: ner, each block the NER model read, then each it didn't. Empty when no setting has a tier.
For a stream, the time the gateway added before the client got the first text: overhead_ms, and the time that text then waited in the guardrails. Null for a response that isn't streamed or that sent no text, and for requests recorded before it was timed.
limits_msrequired
number | null
The limit check, on the request before the provider call, and so part of overhead_ms. Null for a request refused before it, and for requests recorded before it was timed.
guardrailsrequired
object[]
How long each guardrail that ran took, in the order it first ran, by the gateway's clock. A guardrail that a refusal came before doesn't run. Empty for requests recorded before guardrails were timed.
On the request, before the provider call, and so part of overhead_ms.
alongside_msrequired
number | null
Its work at the same time as the provider call, until the work reported: prompt_injection's check, and personal_data's fetch of the pseudonyms kept with a previous_response_id. The answer waits for it only when the provider is faster: for personal_data's before its first text, and for prompt_injection's before its end, or before its first text when its model tier checks a block whose action is cut. Null when it does no such work, or the work didn't report.
response_msrequired
number | null
On the answer, all of its events together, so it grows with the answer's length. Null when the guardrail doesn't read the answer, or no answer reached it.
Why content wasn't kept: retention_none, the policies retain none; not_sent, Alectura refused the request before any provider got it; unanswered, no provider answered it. Content is kept only with an answer, so read a refused request's findings and coverage instead. retention is still what the policies set.
flagged: the model found it, and the request has a finding; for the ner tier, the model found at least one person's name in the block, which the request's findings keep unless it is excluded or inside a longer value, such as an email address. unreadable: the model answered with another word, or a decision model refused. failed: the provider or the NER host refused or failed. timed_out: no answer in 2 seconds, or in the ner tier's time. unserved: no connection the request may use serves a model on the list, or the region has no NER host. not_asked: the block, or part of it, wasn't asked, as the request's questions went to newer text or its file was rewritten for the provider; for the ner tier, the 4 KB went to newer text, the block holds a PDF, or the NER host was busy. Only flagged can change the request.
Requests with any of these findings, each counted once. An hour rolled up before they were counted gives the distinct requests its groups' samples name, which can be too few only where one of its groups had more than five.
requests_by_actionrequired
map<string, integer>
Each action's requests with any of these findings under it, counted as requests is.
Distinct organizations. In a summary's totals, from the directory: those first seen before to and last seen at or after from. In a series point, from that period's rollup: those whose requests in it have ended, minutes behind. So the two can differ.
usersrequired
integer
Distinct users, counted as organizations is.
modelsrequired
map<string, integer>
The requests a provider answered, by the model that answered, a fallback by the id its connection knows it by; one cut before its answer isn't counted.
providersrequired
map<string, integer>
The requests a provider answered, by that provider.
In the hours that overlap the window's last hour: idle without attempts; failing when a request failed at it with no connection left to try, or at least half its attempts failed other than with 429; otherwise throttled when it answered 429; otherwise healthy.
attemptsrequired
integer
throttledrequired
integer
Attempts it answered 429.
errorsrequired
integer
Other attempts that failed: no answer in time, or an error status other than 400, 413 and 422, which refuse the request itself and are tried nowhere else.
fell_backrequired
map<string, integer>
Failed attempts, 429s included, after which the request tried another connection, by that one.
none_leftrequired
integer
Failed attempts, 429s included, after which the request had no connection left to try.
p50_msrequired
integer | null
The median time its answered attempts took, to a stream's first byte or the whole body, estimated from fixed buckets; null if it answered none.
seriesrequired
object[]
Its attempts in each period of the interval asked for that overlaps the window, the whole period, as a summary's series counts them.
eq, ne, in and not_in take any type; on a field that holds several values per request, such as guardrail, eq means that one of them is the value. prefix takes a string. gt to lte take a measure or status. exists and missing take no value.
count takes no field and counts requests. sum, min, max, avg, p50, p95 and p99 take a measure, and skip requests that have none. distinct takes a dimension. p95 is the least value that at least 95% of the values are at or below (the nearest rank), so it is always one of them. It is exact, as SQL's percentile_disc is, not an estimate.
The top groups kept, within each group of the field before this one.
sort
object
Fields
by
string
A computed value's name, or value for the group's own value. Default the first computed value.
order
"asc" | "desc"
QueryValues
Each computed value by its name. A count, or a sum of tokens, is an integer. Money is a decimal string in USD to the nanodollar. An average is a decimal string. A min, max, avg or percentile over no requests is null; a sum over none is 0.
map<string, integer | string | null>
QueryPoint
atrequired
string (date-time)
The start of the point's interval. The first and last points cover only the part inside the period.
Every request that ended before this time is in the answer, as it ended.
groupsrequired
object[]
Ordered by each group-by's sort, then by value. A request without a value of a field is in a group whose value is null. With a field that holds several values per request, a request is in each of its groups, so the groups can add up to more than the total.
What the query read, as Athena counts it; 0 when Athena reused an earlier result. The daily budget counts at least 10 MB for each query that ran, as Athena bills.
What was observed. injection_attempts, secret_probing and illegal_content: three or more requests in an hour with that guardrail's findings (illegal content counts findings). shared_template: what the user wrote, not a tool's result, matching two or more other users' in a day, in a text first sent within the day. full_usage_from_first_hour: within an hour of their first request, a limit of the environment's policies that counts over a day, week or month refused the user once they had used most of it; a per-minute limit never raises it. system_prompt_stripped: the app's usual system prompt missing from most of an hour's requests. spike: 100 or more requests in an hour, ten times their usual. token_resale: active in 20 of the last 24 hours without the app's prompt. roleplay_farm: five or more users sending one system prompt that isn't the app's. topic_variety: far more conversations in an hour than the app's users hold. key_sharing: five or more of the user's clients in an hour. shim_shape: requests from client software the app's users don't call from, as an OpenAI-compatible shim's. The last two read only the client the team forwards in Alectura-User-IP and Alectura-User-Agent. Every kind can suspend the user through abuse.suspend_at.
A connection's alert. It is raised once and cleared once, and both events carry the same id.
objectrequired
"alert"
idrequired
string
kindrequired
"throttled" | "fell_back" | "no_fallback_left"
throttled: it answered 429 in each of minutes minutes in a row that it was tried. fell_back: a request tried another connection after it failed. no_fallback_left: a request failed at it with no connection left to try.
For throttled, the minutes the settings named; null otherwise.
raised_atrequired
string (date-time)
The start of the minute whose requests raised it.
cleared_atrequired
string (date-time) | null
10 minutes after the last request that had it; null until it clears.
AlertKind
A connection's Alert, or limit_threshold: an organization or user passing 80% or 95% of a limit, or 100% of a warn limit, which is limit.threshold_crossed.
The events it receives; empty for every event, including types added later. webhook_endpoint.test goes only to the endpoint tested, so it can't be listed.
One event sent to one endpoint. It is tried at once, then after 1 minute, 10 minutes, 1 hour and 12 hours; after the fifth failure it has failed, and the endpoint is disabled.
Why no response came: timeout, connection_refused, tls_error, dns_error, connection_closed, invalid_url, address_not_public when the host resolved only to addresses that aren't public, or, for any other cause, connection_failed.
A draft as a replay takes it: a new draft (match and settings), or changes to an existing policy (policy_id with either). A draft that a save refuses is refused.
Up to 50 identities, each as a request names it. One that names an organization and no plan has the plan that the organization's latest request named, as its requests do.
Where to upload the logs, while the assessment awaits them.
progressrequired
object | null
Where the assessment is while it is queued or running, as of its last checkpoint: null until it has read its first part of the upload, and once it ends.
The provider formats are one request per line, with its response, in the provider's own format, wrapped with timestamp, user, organization and plan (and model for Gemini, whose request leaves it out). bedrock_invocation_logs_jsonl is Bedrock's S3 model invocation logs, decompressed and concatenated into one file, leaving out the bodies under data/ (find . -name '*.json.gz' ! -path '*/data/*' -exec gunzip -c {} + > logs.jsonl). The user, organization and plan come from each invocation's requestMetadata (user, organization, plan), or the user from an Anthropic body's metadata.user_id; an invocation with neither is rejected as missing_user, since the log's own caller is the team's server. A body over 100 KB, which Bedrock moves to S3, counts without its text (rows.unread), and needs its user in requestMetadata. An upload is at most 5 GiB, and a compressed one fails. The metadata formats carry no prompts: each row is timestamp, user, organization, plan, model, input_tokens, output_tokens, ip_hash and system_prompt_hash, as a JSON object per line or as CSV under a header line naming the columns. timestamp, user and model are required. ip_hash is the end user's address, as in Alectura-User-IP, never your servers'. The hashes can be any stable hash you choose. Signals that read what users wrote (shared templates, prompt injection, secrets) are reported as unavailable for a metadata assessment.
A completed assessment's report (J5.3): the users analyzed, the suspicious ones and their share of tokens, the cost estimated at list prices, and the most suspicious users, each signal naming lines of the upload behind it.
Signals the assessment couldn't look for: those that read what users wrote, for a metadata assessment, and full_usage_from_first_hour, which only a limit's refusal raises, when no limit in the environment's current policies applies to the upload's users and the log shows none refusing them.
partial_signals
string[]
Signals that read what users wrote and saw only some rows, because others' text wasn't in the log (rows.unread). Empty when every row's text was read; absent from older reports.
A message, a recording, or both. Feedback with neither is refused with an error on message.
pagerequired
string (uri)
The dashboard page the feedback is about.
message
string
screenshot
object
The page as the member saw it, with anything on it that shows a secret blanked.
Fields
content_typerequired
"image/png" | "image/webp" | "image/jpeg"
bytesrequired
integer
recording
object
What the member said instead of, or as well as, a message.
Fields
content_typerequired
"audio/webm" | "audio/mp4" | "audio/ogg"
bytesrequired
integer
Example
{
"page": "https://app.alecturalabs.com/env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/requests",
"message": "The export button does nothing on this page.",
"screenshot": {"content_type": "image/png", "bytes": 482113}
}
DashboardErrorReport
pagerequired
string
The page's route, with its parameters named, such as /:environmentId/requests/:id. It has no digits or underscores, which every id has.
call
string
The call whose answer couldn't be read, as its method and path in this contract, such as GET /requests/{id}/content. Absent where the dashboard can't tell which.
kindrequired
"unreadable" | "render"
unreadable: a successful answer the dashboard couldn't read. render: the page failed as it rendered.