Docs · version 1

Management API reference

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
read Config, organizations, users, request metadata, findings, signals, events, summaries
read_content 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.

4XXError

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.

5XXError

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.

Organizations

Your customers, as requests name them.

GET/organizations

List organizationsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

suspendedqueryboolean

Only suspended ones, or only ones not suspended.

Responses

200OrganizationList

A page of organizations, newest first by default.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/organizations' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "organization",
      "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "external_id": "acme",
      "name": "Acme",
      "metadata": {"crm_id": "4821"},
      "plan": "pro",
      "suspended": false,
      "state": "active",
      "first_seen_at": "2026-09-29T14:02:11.482Z",
      "last_seen_at": "2026-09-29T14:02:11.482Z",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/organizations

Create an organizationPermission: manage

Organizations are also created by the first request that names them. Creating one first sets its name and metadata before any traffic.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

OrganizationCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/organizations' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"}
}'

Example response · 201

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"},
  "plan": "pro",
  "suspended": false,
  "state": "active",
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/organizations/{id}

Get an organizationPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredOrganizationId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/organizations/org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"},
  "plan": "pro",
  "suspended": false,
  "state": "active",
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/organizations/{id}

Update an organizationPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredOrganizationId

Body

OrganizationUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/organizations/org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "metadata": {"crm_id": "4821"}}'

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"},
  "plan": "pro",
  "suspended": false,
  "state": "active",
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/organizations/{id}

Delete an organizationPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredOrganizationId

Responses

202Organization

The organization, in the deleting state.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/organizations/org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 202

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"},
  "plan": "pro",
  "suspended": false,
  "state": "deleting",
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/organizations/external_id/{external_id}

Get an organization by your identifierPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

external_idpath, requiredExternalId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/organizations/external_id/string' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"},
  "plan": "pro",
  "suspended": false,
  "state": "active",
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

Users

The people or accounts in your product that requests are made for.

GET/users

List usersPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId
suspendedqueryboolean

Only suspended ones, or only ones not suspended.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/users' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "external_id": "user_42",
      "name": "Ada Lovelace",
      "metadata": {"crm_id": "4821"},
      "suspended": false,
      "signals": [
        {
          "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "kind": "injection_attempts",
          "score": 0.5
        }
      ],
      "first_seen_at": "2026-09-29T14:02:11.482Z",
      "last_seen_at": "2026-09-29T14:02:11.482Z",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/users

Create a userPermission: manage

Users are also created by the first request that names them.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

UserCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/users' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"crm_id": "4821"}
}'

Example response · 201

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "user_42",
  "name": "Ada Lovelace",
  "metadata": {"crm_id": "4821"},
  "suspended": false,
  "signals": [
    {
      "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "kind": "injection_attempts",
      "score": 0.5
    }
  ],
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/users/{id}

Get a userPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredUserId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/users/user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "user_42",
  "name": "Ada Lovelace",
  "metadata": {"crm_id": "4821"},
  "suspended": false,
  "signals": [
    {
      "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "kind": "injection_attempts",
      "score": 0.5
    }
  ],
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/users/{id}

Update a userPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredUserId

Body

UserUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/users/user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "metadata": {"crm_id": "4821"}}'

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "user_42",
  "name": "Ada Lovelace",
  "metadata": {"crm_id": "4821"},
  "suspended": false,
  "signals": [
    {
      "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "kind": "injection_attempts",
      "score": 0.5
    }
  ],
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/users/external_id/{external_id}

Get a user by your identifierPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

external_idpath, requiredExternalId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/users/external_id/string' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "user_42",
  "name": "Ada Lovelace",
  "metadata": {"crm_id": "4821"},
  "suspended": false,
  "signals": [
    {
      "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "kind": "injection_attempts",
      "score": 0.5
    }
  ],
  "first_seen_at": "2026-09-29T14:02:11.482Z",
  "last_seen_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/related_users

Users who share prompt templates with a userPermission: read

Users whose requests share template fingerprints with this user's, most shared first.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

user_idquery, requiredUserId
limitqueryinteger

How many objects a page holds.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/related_users?user_id=user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "related_user",
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "shared_fingerprints": 1
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/organization_memberships

List which users have made requests for which organizationsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId
user_idqueryUserId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/organization_memberships' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "organization_membership",
      "id": "om_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "organization": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "first_seen_at": "2026-09-29T14:02:11.482Z",
      "last_seen_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

Suspensions

Blocking a user's or an organization's requests.

GET/suspensions

List suspensionsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId
user_idqueryUserId
activequeryboolean

Only suspensions in force, or only lifted and expired ones.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/suspensions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "suspension",
      "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "organization": null,
      "user": {
        "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "user_42"
      },
      "reason": "abuse",
      "note": "Scraping answers at volume.",
      "created_by": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z",
      "expires_at": "2026-10-09T00:00:00.000Z",
      "lifted_at": null,
      "lifted_by": null
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/suspensions

Suspend a user or an organizationPermission: manage

Every gateway task refuses the suspended party's next request, within 10 seconds.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

SuspensionCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/suspensions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "reason": "abuse",
  "note": "Scraping answers at volume.",
  "expires_at": "2026-10-09T00:00:00.000Z"
}'

Example response · 201

{
  "object": "suspension",
  "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "organization": null,
  "user": {
    "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "user_42"
  },
  "reason": "abuse",
  "note": "Scraping answers at volume.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": "2026-10-09T00:00:00.000Z",
  "lifted_at": null,
  "lifted_by": null
}

GET/suspensions/{id}

Get a suspensionPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredSuspensionId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/suspensions/suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "suspension",
  "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "organization": null,
  "user": {
    "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "user_42"
  },
  "reason": "abuse",
  "note": "Scraping answers at volume.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": "2026-10-09T00:00:00.000Z",
  "lifted_at": null,
  "lifted_by": null
}

POST/suspensions/{id}/lift

Lift a suspensionPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

idpath, requiredSuspensionId

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/suspensions/suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/lift' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "suspension",
  "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "organization": null,
  "user": {
    "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "user_42"
  },
  "reason": "abuse",
  "note": "Scraping answers at volume.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": "2026-10-09T00:00:00.000Z",
  "lifted_at": null,
  "lifted_by": null
}

Policies

Matches and settings, and how they combine.

GET/policies

List policiesPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/policies' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "policy",
      "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Free plan",
      "description": "Tighter limits and a cheaper model for the free plan.",
      "owner": {"type": "environment"},
      "match": {"plan": "free"},
      "settings": {
        "routing": {"models": {"only": ["gpt-5-mini"]}},
        "limits": {
          "requests": [{"per": "user", "period": "minute", "amount": 20}],
          "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
        },
        "guardrails": {
          "secrets": {"action": "redact"},
          "personal_data": {"action": "pseudonymize"}
        }
      },
      "version": 1,
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/policies

Create a policyPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

PolicyCreate

Responses

201Policy

Created, at version 1. Every gateway task applies it within 10 seconds; until then, requests get the policies as they were.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/policies' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  }
}'

Example response · 201

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "owner": {"type": "environment"},
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/policies/{id}

Get a policyPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredPolicyId

Responses

200Policy

The policy, at its current version.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/policies/policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "owner": {"type": "environment"},
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/policies/{id}

Update a policyPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredPolicyId

Body

PolicyUpdate

Responses

200Policy

The policy, at its new version, which every gateway task applies within 10 seconds.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/policies/policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "limits": {
      "spend": [{"per": "user", "period": "day", "amount": "1.00"}]
    }
  }
}'

Example response · 200

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "owner": {"type": "environment"},
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/policies/{id}

Delete a policyPermission: manage

Every gateway task stops applying it within 10 seconds. Its versions are kept, so requests that matched it still explain themselves.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredPolicyId

Responses

200Policy

The deleted policy, at the version its deletion made.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/policies/policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "owner": {"type": "environment"},
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/policies/{id}/versions

List a policy's versionsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredPolicyId
limitqueryinteger

How many objects a page holds.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

beforequeryinteger

A version number.

afterqueryinteger

A version number.

Responses

200PolicyVersionList

A page of versions, newest first by default.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/policies/policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/versions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "policy_version",
      "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "version": 1,
      "name": "Globex",
      "match": {"organization": "globex"},
      "settings": {
        "routing": {
          "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
          "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
          "data_terms": {"retention": "zero", "training": "no"}
        },
        "retention": {"content": "none"},
        "limits": {
          "requests": [{"per": "user", "period": "minute", "amount": 60}],
          "spend": [
            {"per": "user", "period": "day", "amount": "2.00"},
            {
              "per": "organization",
              "period": "month",
              "amount": "500.00",
              "action": "warn"
            }
          ]
        },
        "guardrails": {
          "secrets": {"action": "redact"},
          "personal_data": {
            "action": "pseudonymize",
            "parts": ["user", "tool_result"],
            "kinds": ["email", "phone"],
            "exclusions": ["support@acme.example"]
          },
          "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
          "illegal_content": {"action": "warn"},
          "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
          "tool_calls": {
            "action": "cut",
            "allowed": [
              {"name": "read_file"},
              {
                "name": "send_email",
                "arguments": {
                  "type": "object",
                  "properties": {
                    "to": {
                      "type": "string",
                      "pattern": "^[^@\\s]+@acme\\.example$"
                    }
                  },
                  "required": ["to"]
                }
              }
            ]
          },
          "custom_patterns": {
            "action": "redact",
            "patterns": [
              {"name": "employee_id", "regex": "EMP-\\d{6}"},
              {
                "name": "codenames",
                "words": ["Falcon", "Project Heron"]
              }
            ]
          },
          "system_prompt_leak": {"action": "cut"},
          "grounding": {"action": "warn"}
        },
        "uninspected": "allow",
        "abuse": {"suspend_at": 0.9}
      },
      "deleted": false,
      "created_by": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/effective_policy

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

organizationqueryExternalId

The Alectura-Organization value.

userqueryExternalId

The Alectura-User value.

planqueryExternalId

The Alectura-Plan value.

tagsquerystring

The Alectura-Tags value, such as feature=search,env=prod.

modelquerystring

A model to trace routing for, and list the connections it would try.

Responses

200EffectivePolicy

The combined settings, with the policy behind each.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/effective_policy' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "effective_policy",
  "identity": {
    "organization": "acme",
    "user": "user_42",
    "plan": "pro",
    "tags": {"key": "enterprise"}
  },
  "policies": [{"id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T", "version": 1}],
  "settings": {
    "routing": {
      "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
      "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
      "data_terms": {"retention": "zero", "training": "no"}
    },
    "retention": {"content": "none"},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 60}],
      "spend": [
        {"per": "user", "period": "day", "amount": "2.00"},
        {
          "per": "organization",
          "period": "month",
          "amount": "500.00",
          "action": "warn"
        }
      ]
    },
    "guardrails": {
      "secrets": [
        {
          "action": "warn",
          "mode": "monitor",
          "parts": ["system"]
        }
      ],
      "personal_data": [
        {
          "action": "warn",
          "mode": "monitor",
          "parts": ["system"],
          "kinds": ["email"],
          "exclusions": ["exclusions"],
          "exclude_test_cards": false,
          "tier": "local"
        }
      ],
      "prompt_injection": [
        {
          "action": "warn",
          "mode": "monitor",
          "parts": ["system"],
          "tier": "local"
        }
      ],
      "illegal_content": [
        {
          "action": "warn",
          "mode": "monitor",
          "parts": ["system"],
          "kinds": ["violent_crimes"],
          "tier": "local"
        }
      ],
      "moderation": [
        {
          "action": "warn",
          "mode": "monitor",
          "parts": ["system"],
          "kinds": ["hate"],
          "tier": "local"
        }
      ],
      "tool_calls": [
        {
          "action": "cut",
          "allowed": [
            {"name": "mcp__github__*"},
            {
              "name": "send_email",
              "arguments": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^[^@\\s]+@acme\\.example$"
                  }
                },
                "required": ["to"]
              }
            }
          ],
          "denied": ["mcp__github__delete_repo"]
        }
      ],
      "custom_patterns": [
        {
          "action": "warn",
          "parts": ["system"],
          "patterns": [
            {
              "name": "employee_id",
              "regex": "regex",
              "words": ["words"]
            }
          ]
        }
      ],
      "system_prompt_leak": [{"action": "warn"}],
      "grounding": [{"action": "warn"}]
    },
    "uninspected": "allow",
    "abuse": {"suspend_at": 0.9}
  },
  "sources": {"retention.content": ["policy_01M3PQG7FEV8Q4X0M5R7T9W2YA"]},
  "decided_by_team": ["decided_by_team"],
  "trace": {
    "routing.models": {
      "seed": [{"member": "member", "rank": 1}],
      "steps": [
        {
          "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "add": {"key": {"rank": 1}},
          "only": ["only"],
          "remove": ["remove"]
        }
      ],
      "result": [{"member": "member", "rank": 1}]
    },
    "routing.regions": {
      "seed": [{"member": "member", "rank": 1}],
      "steps": [
        {
          "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "add": {"key": {"rank": 1}},
          "only": ["only"],
          "remove": ["remove"]
        }
      ],
      "result": [{"member": "member", "rank": 1}]
    },
    "routing.connections": {
      "seed": [{"member": "member", "rank": 1}],
      "steps": [
        {
          "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "add": {"key": {"rank": 1}},
          "only": ["only"],
          "remove": ["remove"]
        }
      ],
      "result": [{"member": "member", "rank": 1}]
    }
  },
  "candidates": [
    {
      "position": 1,
      "connection": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "model": "claude-sonnet-5-5",
      "model_rank": 1,
      "region": "us",
      "region_rank": 1,
      "rank": 1
    }
  ]
}

POST/effective_policy/preview

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 user plan or tags; and each side is as GET /effective_policy shows it there.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Body

EffectivePolicyPreview

Responses

200EffectivePolicyChangeList

For each identity in the order given, its effective policy before and after.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/effective_policy/preview' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "match": {"organization": "globex"},
  "settings": {
    "routing": {
      "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
      "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
      "data_terms": {"retention": "zero", "training": "no"}
    },
    "retention": {"content": "none"},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 60}],
      "spend": [
        {"per": "user", "period": "day", "amount": "2.00"},
        {
          "per": "organization",
          "period": "month",
          "amount": "500.00",
          "action": "warn"
        }
      ]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {
        "action": "pseudonymize",
        "parts": ["user", "tool_result"],
        "kinds": ["email", "phone"],
        "exclusions": ["support@acme.example"]
      },
      "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
      "illegal_content": {"action": "warn"},
      "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
      "tool_calls": {
        "action": "cut",
        "allowed": [
          {"name": "read_file"},
          {
            "name": "send_email",
            "arguments": {
              "type": "object",
              "properties": {
                "to": {
                  "type": "string",
                  "pattern": "^[^@\\s]+@acme\\.example$"
                }
              },
              "required": ["to"]
            }
          }
        ]
      },
      "custom_patterns": {
        "action": "redact",
        "patterns": [
          {"name": "employee_id", "regex": "EMP-\\d{6}"},
          {
            "name": "codenames",
            "words": ["Falcon", "Project Heron"]
          }
        ]
      },
      "system_prompt_leak": {"action": "cut"},
      "grounding": {"action": "warn"}
    },
    "uninspected": "allow",
    "abuse": {"suspend_at": 0.9}
  },
  "identities": [
    {
      "organization": "acme",
      "user": "user_42",
      "plan": "pro",
      "tags": {"key": "enterprise"}
    }
  ]
}'

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "effective_policy_change",
      "before": {
        "object": "effective_policy",
        "identity": {
          "organization": "acme",
          "user": "user_42",
          "plan": "pro",
          "tags": {"key": "enterprise"}
        },
        "policies": [
          {
            "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "version": 1
          }
        ],
        "settings": {
          "routing": {
            "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
            "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
            "data_terms": {"retention": "zero", "training": "no"}
          },
          "retention": {"content": "none"},
          "limits": {
            "requests": [{"per": "user", "period": "minute", "amount": 60}],
            "spend": [
              {"per": "user", "period": "day", "amount": "2.00"},
              {
                "per": "organization",
                "period": "month",
                "amount": "500.00",
                "action": "warn"
              }
            ]
          },
          "guardrails": {
            "secrets": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"]
              }
            ],
            "personal_data": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["email"],
                "exclusions": ["exclusions"],
                "exclude_test_cards": false,
                "tier": "local"
              }
            ],
            "prompt_injection": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "tier": "local"
              }
            ],
            "illegal_content": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["violent_crimes"],
                "tier": "local"
              }
            ],
            "moderation": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["hate"],
                "tier": "local"
              }
            ],
            "tool_calls": [
              {
                "action": "cut",
                "allowed": [
                  {"name": "mcp__github__*"},
                  {
                    "name": "send_email",
                    "arguments": {
                      "type": "object",
                      "properties": {
                        "to": {
                          "type": "string",
                          "pattern": "^[^@\\s]+@acme\\.example$"
                        }
                      },
                      "required": ["to"]
                    }
                  }
                ],
                "denied": ["mcp__github__delete_repo"]
              }
            ],
            "custom_patterns": [
              {
                "action": "warn",
                "parts": ["system"],
                "patterns": [
                  {
                    "name": "employee_id",
                    "regex": "regex",
                    "words": ["words"]
                  }
                ]
              }
            ],
            "system_prompt_leak": [{"action": "warn"}],
            "grounding": [{"action": "warn"}]
          },
          "uninspected": "allow",
          "abuse": {"suspend_at": 0.9}
        },
        "sources": {
          "retention.content": ["policy_01M3PQG7FEV8Q4X0M5R7T9W2YA"]
        },
        "decided_by_team": ["decided_by_team"],
        "trace": {
          "routing.models": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          },
          "routing.regions": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          },
          "routing.connections": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          }
        },
        "candidates": [
          {
            "position": 1,
            "connection": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "model": "claude-sonnet-5-5",
            "model_rank": 1,
            "region": "us",
            "region_rank": 1,
            "rank": 1
          }
        ]
      },
      "after": {
        "object": "effective_policy",
        "identity": {
          "organization": "acme",
          "user": "user_42",
          "plan": "pro",
          "tags": {"key": "enterprise"}
        },
        "policies": [
          {
            "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "version": 1
          }
        ],
        "settings": {
          "routing": {
            "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
            "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
            "data_terms": {"retention": "zero", "training": "no"}
          },
          "retention": {"content": "none"},
          "limits": {
            "requests": [{"per": "user", "period": "minute", "amount": 60}],
            "spend": [
              {"per": "user", "period": "day", "amount": "2.00"},
              {
                "per": "organization",
                "period": "month",
                "amount": "500.00",
                "action": "warn"
              }
            ]
          },
          "guardrails": {
            "secrets": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"]
              }
            ],
            "personal_data": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["email"],
                "exclusions": ["exclusions"],
                "exclude_test_cards": false,
                "tier": "local"
              }
            ],
            "prompt_injection": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "tier": "local"
              }
            ],
            "illegal_content": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["violent_crimes"],
                "tier": "local"
              }
            ],
            "moderation": [
              {
                "action": "warn",
                "mode": "monitor",
                "parts": ["system"],
                "kinds": ["hate"],
                "tier": "local"
              }
            ],
            "tool_calls": [
              {
                "action": "cut",
                "allowed": [
                  {"name": "mcp__github__*"},
                  {
                    "name": "send_email",
                    "arguments": {
                      "type": "object",
                      "properties": {
                        "to": {
                          "type": "string",
                          "pattern": "^[^@\\s]+@acme\\.example$"
                        }
                      },
                      "required": ["to"]
                    }
                  }
                ],
                "denied": ["mcp__github__delete_repo"]
              }
            ],
            "custom_patterns": [
              {
                "action": "warn",
                "parts": ["system"],
                "patterns": [
                  {
                    "name": "employee_id",
                    "regex": "regex",
                    "words": ["words"]
                  }
                ]
              }
            ],
            "system_prompt_leak": [{"action": "warn"}],
            "grounding": [{"action": "warn"}]
          },
          "uninspected": "allow",
          "abuse": {"suspend_at": 0.9}
        },
        "sources": {
          "retention.content": ["policy_01M3PQG7FEV8Q4X0M5R7T9W2YA"]
        },
        "decided_by_team": ["decided_by_team"],
        "trace": {
          "routing.models": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          },
          "routing.regions": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          },
          "routing.connections": {
            "seed": [{"member": "member", "rank": 1}],
            "steps": [
              {
                "policy": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
                "add": {"key": {"rank": 1}},
                "only": ["only"],
                "remove": ["remove"]
              }
            ],
            "result": [{"member": "member", "rank": 1}]
          }
        },
        "candidates": [
          {
            "position": 1,
            "connection": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "model": "claude-sonnet-5-5",
            "model_rank": 1,
            "region": "us",
            "region_rank": 1,
            "rank": 1
          }
        ]
      }
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

Connections

Ways to reach a model provider.

GET/connections

List connectionsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId

Only the connections this organization owns.

providerqueryProvider
statequeryConnectionState

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/connections' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "connection",
      "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "OpenAI EU",
      "provider": "openai",
      "owner": {"type": "environment"},
      "base_url": "https://eu.api.openai.com/v1",
      "aws_region": null,
      "inference_profile": null,
      "azure_resource": null,
      "azure_region": null,
      "vertex_project": null,
      "vertex_location": null,
      "openai_project": null,
      "region": "eu",
      "models": ["gpt-5", "gpt-5-mini"],
      "application_inference_profiles": {},
      "data_terms": {"retention": "zero", "training": "no"},
      "credential": {"type": "api_key", "hint": "Qk3x"},
      "aws_external_id": null,
      "state": "draft",
      "cooling_down_until": null,
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/connections

Create a connectionPermission: manage

A new connection is a draft, and routes nothing until it is activated.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

ConnectionCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/connections' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "OpenAI EU",
  "provider": "openai",
  "base_url": "https://eu.api.openai.com/v1",
  "models": ["gpt-5", "gpt-5-mini"],
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "api_key": "sk-proj-…"}
}'

Example response · 201

{
  "object": "connection",
  "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "OpenAI EU",
  "provider": "openai",
  "owner": {"type": "environment"},
  "base_url": "https://eu.api.openai.com/v1",
  "aws_region": null,
  "inference_profile": null,
  "azure_resource": null,
  "azure_region": null,
  "vertex_project": null,
  "vertex_location": null,
  "openai_project": null,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "application_inference_profiles": {},
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "hint": "Qk3x"},
  "aws_external_id": null,
  "state": "draft",
  "cooling_down_until": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/connections/{id}

Get a connectionPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredConnectionId

Responses

200Connection

The connection. Its credential is never returned.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/connections/conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "connection",
  "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "OpenAI EU",
  "provider": "openai",
  "owner": {"type": "environment"},
  "base_url": "https://eu.api.openai.com/v1",
  "aws_region": null,
  "inference_profile": null,
  "azure_resource": null,
  "azure_region": null,
  "vertex_project": null,
  "vertex_location": null,
  "openai_project": null,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "application_inference_profiles": {},
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "hint": "Qk3x"},
  "aws_external_id": null,
  "state": "draft",
  "cooling_down_until": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/connections/{id}

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredConnectionId

Body

ConnectionUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/connections/conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "models": ["models"],
  "application_inference_profiles": {
    "us.anthropic.claude-haiku-4-5-20251001-v1:0": "arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/a1b2c3d4e5f6"
  },
  "data_terms": {"retention": "undeclared", "training": "undeclared"},
  "credential": {"type": "api_key", "api_key": "sk-proj-…"},
  "state": "draft"
}'

Example response · 200

{
  "object": "connection",
  "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "OpenAI EU",
  "provider": "openai",
  "owner": {"type": "environment"},
  "base_url": "https://eu.api.openai.com/v1",
  "aws_region": null,
  "inference_profile": null,
  "azure_resource": null,
  "azure_region": null,
  "vertex_project": null,
  "vertex_location": null,
  "openai_project": null,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "application_inference_profiles": {},
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "hint": "Qk3x"},
  "aws_external_id": null,
  "state": "draft",
  "cooling_down_until": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/connections/{id}

Delete a connectionPermission: manage

Its credential is destroyed. Requests that used it keep its id.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredConnectionId

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/connections/conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "connection",
  "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "OpenAI EU",
  "provider": "openai",
  "owner": {"type": "environment"},
  "base_url": "https://eu.api.openai.com/v1",
  "aws_region": null,
  "inference_profile": null,
  "azure_resource": null,
  "azure_region": null,
  "vertex_project": null,
  "vertex_location": null,
  "openai_project": null,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "application_inference_profiles": {},
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "hint": "Qk3x"},
  "aws_external_id": null,
  "state": "draft",
  "cooling_down_until": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/connections/{id}/test

Test a connectionPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredConnectionId
Idempotency-Keyheaderstring

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.

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/connections/conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/test' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "connection_test",
  "connection_id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "passed": false,
  "checks": [
    {
      "name": "Acme",
      "passed": false,
      "reason": "Set by our scripts.",
      "message": "The provider answered 401.",
      "upstream_status": 1
    }
  ],
  "created_at": "2026-09-29T14:02:11.482Z"
}

Content store

Where content kept under team retention goes, in your own AWS account.

GET/content_store

Get the content storePermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Responses

200ContentStore | null

The content store, or null while the environment has none.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/content_store' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "content_store",
  "bucket": "acme-alectura-content",
  "region": "eu-west-1",
  "prefix": "alectura/",
  "role_arn": "arn:aws:iam::123456789012:role/alectura-content",
  "external_id": "acme",
  "state": "draft",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/content_store

Set the content storePermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

ContentStoreSet

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/content_store' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bucket": "acme-alectura-content",
  "region": "eu-west-1",
  "prefix": "alectura/",
  "role_arn": "arn:aws:iam::123456789012:role/alectura-content"
}'

Example response · 200

{
  "object": "content_store",
  "bucket": "acme-alectura-content",
  "region": "eu-west-1",
  "prefix": "alectura/",
  "role_arn": "arn:aws:iam::123456789012:role/alectura-content",
  "external_id": "acme",
  "state": "draft",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/content_store

Remove the content storePermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/content_store' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "content_store",
  "bucket": "acme-alectura-content",
  "region": "eu-west-1",
  "prefix": "alectura/",
  "role_arn": "arn:aws:iam::123456789012:role/alectura-content",
  "external_id": "acme",
  "state": "draft",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/content_store/test

Test the content storePermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Responses

200ContentStoreTest

The test's result, and the store after it.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/content_store/test' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "content_store_test",
  "passed": false,
  "message": "The provider answered 401.",
  "content_store": {
    "object": "content_store",
    "bucket": "acme-alectura-content",
    "region": "eu-west-1",
    "prefix": "alectura/",
    "role_arn": "arn:aws:iam::123456789012:role/alectura-content",
    "external_id": "acme",
    "state": "draft",
    "created_at": "2026-09-29T14:02:11.482Z",
    "updated_at": "2026-09-29T14:02:11.482Z"
  }
}

API keys

Sending keys for the gateway, and management keys for this API.

GET/api_keys

List API keysPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

typequeryApiKeyType
statequeryApiKeyState

Responses

200ApiKeyList

A page of keys, without their secrets.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/api_keys' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "api_key",
      "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Acme",
      "type": "sending",
      "permissions": ["send"],
      "label": "sk-alectura-eu-live-…2Yl4IC",
      "state": "active",
      "expires_at": null,
      "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
      "created_by": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/api_keys

Create an API keyPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

ApiKeyCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/api_keys' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production servers"}'

Example response · 201

{
  "object": "api_key",
  "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "type": "sending",
  "permissions": ["send"],
  "label": "sk-alectura-eu-live-…2Yl4IC",
  "state": "active",
  "expires_at": null,
  "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z",
  "secret": "sk-alectura-eu-live-0123456789abcdefghijABCDEFGHIJ01234567892Yl4IC"
}

GET/api_keys/{id}

Get an API keyPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredApiKeyId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/api_keys/key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "api_key",
  "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "type": "sending",
  "permissions": ["send"],
  "label": "sk-alectura-eu-live-…2Yl4IC",
  "state": "active",
  "expires_at": null,
  "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/api_keys/{id}

Rename, disable, enable or set the expiry of an API keyPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredApiKeyId

Body

ApiKeyUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/api_keys/key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "state": "active", "expires_at": null}'

Example response · 200

{
  "object": "api_key",
  "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "type": "sending",
  "permissions": ["send"],
  "label": "sk-alectura-eu-live-…2Yl4IC",
  "state": "active",
  "expires_at": null,
  "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/api_keys/{id}

Revoke an API keyPermission: manage

Every gateway task refuses a sending key within 10 seconds, and the management API refuses a management key at once. A revoked key can't be restored.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredApiKeyId

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/api_keys/key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "api_key",
  "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "type": "sending",
  "permissions": ["send"],
  "label": "sk-alectura-eu-live-…2Yl4IC",
  "state": "active",
  "expires_at": null,
  "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/api_keys/{id}/rotate

Rotate an API key's secretPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

idpath, requiredApiKeyId

Body

grace_period_secondsinteger

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/api_keys/key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/rotate' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grace_period_seconds": 86400}'

Example response · 200

{
  "object": "api_key",
  "id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "type": "sending",
  "permissions": ["send"],
  "label": "sk-alectura-eu-live-…2Yl4IC",
  "state": "active",
  "expires_at": null,
  "previous_secret_expires_at": "2026-09-29T14:02:11.482Z",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z",
  "secret": "sk-alectura-eu-live-0123456789abcdefghijABCDEFGHIJ01234567892Yl4IC"
}

Admin portal

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Body

PortalSessionCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/portal_sessions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "features": ["policies"],
  "setting_groups": ["regions", "guardrails"]
}'

Example response · 201

{
  "object": "portal_session",
  "url": "https://app.alecturalabs.com/portal.html#ps-alectura-us-eyJ0.c2ln",
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "features": ["policies"],
  "setting_groups": ["regions"],
  "expires_at": "2026-09-29T14:02:11.482Z"
}

Requests

What each request did, and its content.

GET/requests

List requestsPermission: read

About 2 seconds behind the gateway. Poll with after and order=asc for a live tail.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId
user_idqueryUserId
conversation_idqueryConversationId
verdictqueryVerdict
modelquerystring

The model the request named.

connection_idqueryConnectionId
policy_idqueryPolicyId
guardrailqueryGuardrail

Only requests with a finding from this guardrail.

failedqueryboolean

Only requests that failed, as the summary's errors counts them, or only the rest.

created_afterquerystring (date-time)

Only objects created after this time.

created_beforequerystring (date-time)

Only objects created before this time.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/requests' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "request",
      "id": "req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "state": "pending",
      "created_at": "2026-09-29T14:02:11.482Z",
      "completed_at": null,
      "organization": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "plan": "pro",
      "conversation_id": "conv_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "tags": {"feature": "search"},
      "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "endpoint": "openai.chat_completions",
      "model": "claude-sonnet-5-5",
      "stream": false,
      "status": 1,
      "verdict": "passed",
      "refusal": {
        "code": "user_suspended",
        "message": "The provider answered 401.",
        "limit": {
          "kind": "requests",
          "per": "user",
          "period": "minute",
          "amount": "amount",
          "used": "used",
          "requested": "requested",
          "resets_at": "2026-09-29T14:02:11.482Z",
          "tags": {"feature": "search"}
        }
      },
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "attempts": [
        {
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "model": "claude-sonnet-5-5",
          "started_at": "2026-09-29T14:02:11.482Z",
          "status": 1,
          "error": null,
          "duration_ms": 0.5
        }
      ],
      "policies": [
        {
          "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "version": 1
        }
      ],
      "findings": [
        {
          "object": "finding",
          "id": "finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "guardrail": "secrets",
          "kind": "injection_attempts",
          "action": "warn",
          "block": 1,
          "part": "system"
        }
      ],
      "coverage": [
        {
          "block": 1,
          "part": "system",
          "modality": "text",
          "inspected_by": ["secrets"],
          "reason": "images_uninspected"
        }
      ],
      "checks": [
        {
          "guardrail": "secrets",
          "block": 1,
          "model": "claude-sonnet-5-5",
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "outcome": "flagged",
          "duration_ms": 0.5,
          "input_tokens": 1,
          "output_tokens": 1,
          "cost": {
            "amount": "2.00",
            "currency": "USD",
            "estimated": false
          }
        }
      ],
      "usage": {
        "input_tokens": 1,
        "output_tokens": 1,
        "cache_read_input_tokens": 1,
        "cache_creation_input_tokens": 1,
        "reasoning_tokens": 1,
        "estimated": false,
        "raw": {}
      },
      "cost": {"amount": "2.00", "currency": "USD", "estimated": false},
      "timings": {
        "overhead_ms": 0.5,
        "first_byte_ms": 0.5,
        "duration_ms": 0.5,
        "first_token_overhead_ms": 0.5,
        "limits_ms": 0.5,
        "guardrails": [
          {
            "guardrail": "secrets",
            "request_ms": 0.5,
            "alongside_ms": 0.5,
            "response_ms": 0.5
          }
        ]
      },
      "content": {
        "retained": false,
        "retention": "none",
        "expires_at": null,
        "reason": "retention_none"
      }
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/requests/{id}

Get a requestPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredRequestId

Responses

200Request

The request's record. Its content is fetched separately.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/requests/req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "request",
  "id": "req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "pending",
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null,
  "organization": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "plan": "pro",
  "conversation_id": "conv_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "tags": {"feature": "search"},
  "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "endpoint": "openai.chat_completions",
  "model": "claude-sonnet-5-5",
  "stream": false,
  "status": 1,
  "verdict": "passed",
  "refusal": {
    "code": "user_suspended",
    "message": "The provider answered 401.",
    "limit": {
      "kind": "requests",
      "per": "user",
      "period": "minute",
      "amount": "amount",
      "used": "used",
      "requested": "requested",
      "resets_at": "2026-09-29T14:02:11.482Z",
      "tags": {"feature": "search"}
    }
  },
  "connection": {
    "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "provider": "openai",
    "region": "us"
  },
  "attempts": [
    {
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "model": "claude-sonnet-5-5",
      "started_at": "2026-09-29T14:02:11.482Z",
      "status": 1,
      "error": null,
      "duration_ms": 0.5
    }
  ],
  "policies": [{"id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T", "version": 1}],
  "findings": [
    {
      "object": "finding",
      "id": "finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "guardrail": "secrets",
      "kind": "injection_attempts",
      "action": "warn",
      "block": 1,
      "part": "system"
    }
  ],
  "coverage": [
    {
      "block": 1,
      "part": "system",
      "modality": "text",
      "inspected_by": ["secrets"],
      "reason": "images_uninspected"
    }
  ],
  "checks": [
    {
      "guardrail": "secrets",
      "block": 1,
      "model": "claude-sonnet-5-5",
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "outcome": "flagged",
      "duration_ms": 0.5,
      "input_tokens": 1,
      "output_tokens": 1,
      "cost": {"amount": "2.00", "currency": "USD", "estimated": false}
    }
  ],
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1,
    "cache_read_input_tokens": 1,
    "cache_creation_input_tokens": 1,
    "reasoning_tokens": 1,
    "estimated": false,
    "raw": {}
  },
  "cost": {"amount": "2.00", "currency": "USD", "estimated": false},
  "timings": {
    "overhead_ms": 0.5,
    "first_byte_ms": 0.5,
    "duration_ms": 0.5,
    "first_token_overhead_ms": 0.5,
    "limits_ms": 0.5,
    "guardrails": [
      {
        "guardrail": "secrets",
        "request_ms": 0.5,
        "alongside_ms": 0.5,
        "response_ms": 0.5
      }
    ]
  },
  "content": {
    "retained": false,
    "retention": "none",
    "expires_at": null,
    "reason": "retention_none"
  }
}

GET/requests/{id}/content

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredRequestId
versionquery, requiredContentVersion
viewquery"raw" | "events" | "assembled"

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.

Responses

200object

The content.

410Error

The content has passed its retention, or was never kept.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/requests/req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/content?version=client_request' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

GET/requests/{id}/attachments/{hash}

Get an attachmentPermission: read_content

Recorded as a request.content_read event.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredRequestId
hashpath, requiredstring

Responses

200string

The attachment's bytes, with its media type.

410Error

The attachment has passed its retention, or was never kept.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/requests/req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/attachments/string' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

GET/requests/{id}/conversation

The requests in this request's conversationPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredRequestId
limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

Responses

200RequestList

The conversation's requests, oldest first.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/requests/req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/conversation' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "request",
      "id": "req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "state": "pending",
      "created_at": "2026-09-29T14:02:11.482Z",
      "completed_at": null,
      "organization": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "plan": "pro",
      "conversation_id": "conv_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "tags": {"feature": "search"},
      "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "endpoint": "openai.chat_completions",
      "model": "claude-sonnet-5-5",
      "stream": false,
      "status": 1,
      "verdict": "passed",
      "refusal": {
        "code": "user_suspended",
        "message": "The provider answered 401.",
        "limit": {
          "kind": "requests",
          "per": "user",
          "period": "minute",
          "amount": "amount",
          "used": "used",
          "requested": "requested",
          "resets_at": "2026-09-29T14:02:11.482Z",
          "tags": {"feature": "search"}
        }
      },
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "attempts": [
        {
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "model": "claude-sonnet-5-5",
          "started_at": "2026-09-29T14:02:11.482Z",
          "status": 1,
          "error": null,
          "duration_ms": 0.5
        }
      ],
      "policies": [
        {
          "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "version": 1
        }
      ],
      "findings": [
        {
          "object": "finding",
          "id": "finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
          "guardrail": "secrets",
          "kind": "injection_attempts",
          "action": "warn",
          "block": 1,
          "part": "system"
        }
      ],
      "coverage": [
        {
          "block": 1,
          "part": "system",
          "modality": "text",
          "inspected_by": ["secrets"],
          "reason": "images_uninspected"
        }
      ],
      "checks": [
        {
          "guardrail": "secrets",
          "block": 1,
          "model": "claude-sonnet-5-5",
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "outcome": "flagged",
          "duration_ms": 0.5,
          "input_tokens": 1,
          "output_tokens": 1,
          "cost": {
            "amount": "2.00",
            "currency": "USD",
            "estimated": false
          }
        }
      ],
      "usage": {
        "input_tokens": 1,
        "output_tokens": 1,
        "cache_read_input_tokens": 1,
        "cache_creation_input_tokens": 1,
        "reasoning_tokens": 1,
        "estimated": false,
        "raw": {}
      },
      "cost": {"amount": "2.00", "currency": "USD", "estimated": false},
      "timings": {
        "overhead_ms": 0.5,
        "first_byte_ms": 0.5,
        "duration_ms": 0.5,
        "first_token_overhead_ms": 0.5,
        "limits_ms": 0.5,
        "guardrails": [
          {
            "guardrail": "secrets",
            "request_ms": 0.5,
            "alongside_ms": 0.5,
            "response_ms": 0.5
          }
        ]
      },
      "content": {
        "retained": false,
        "retention": "none",
        "expires_at": null,
        "reason": "retention_none"
      }
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

Findings

Detector matches, and your labels on them.

GET/findings/summary

Findings by guardrail and kind, with samplesPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

fromquery, requiredstring (date-time)

The start of the period, included.

toquery, requiredstring (date-time)

The end of the period, excluded.

guardrailqueryGuardrail
organization_idqueryOrganizationId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/findings/summary?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "findings_summary",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "groups": [
    {
      "guardrail": "secrets",
      "kind": "injection_attempts",
      "action": "warn",
      "count": 1,
      "requests": 1,
      "samples": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"]
    }
  ],
  "requests": 1,
  "requests_by_action": {"warn": 18}
}

GET/findings/{id}/dispositions

List a finding's dispositionsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredFindingId

Responses

200DispositionList

The finding's dispositions, newest first.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/findings/finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/dispositions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "disposition",
      "id": "disposition_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "finding_id": "finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "label": "false_positive",
      "note": "Set by our scripts.",
      "created_by": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/findings/{id}/dispositions

Label a findingPermission: manage

Appends a label. The finding itself never changes, and no policy does either.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredFindingId
Idempotency-Keyheaderstring

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.

Body

DispositionCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/findings/finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/dispositions' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "false_positive", "note": "Set by our scripts."}'

Example response · 201

{
  "object": "disposition",
  "id": "disposition_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "finding_id": "finding_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "label": "false_positive",
  "note": "Set by our scripts.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z"
}

Summaries

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

fromquery, requiredstring (date-time)

The start of the period, included.

toquery, requiredstring (date-time)

The end of the period, excluded.

intervalquery"hour" | "day"

The width of each point in the series.

organization_idqueryOrganizationId
user_idqueryUserId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/summary?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "summary",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "interval": "day",
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "user_id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "totals": {
    "requests": 1,
    "verdicts": {"passed": 1, "modified": 1, "blocked": 1, "cut": 1},
    "errors": 1,
    "input_tokens": 1,
    "output_tokens": 1,
    "cost": {"amount": "2.00", "currency": "USD", "estimated": false},
    "findings": {
      "secrets": 1,
      "personal_data": 1,
      "prompt_injection": 1,
      "illegal_content": 1,
      "moderation": 1,
      "tool_calls": 1,
      "custom_patterns": 1,
      "system_prompt_leak": 1,
      "grounding": 1
    },
    "organizations": 1,
    "users": 1,
    "models": {"key": 1},
    "providers": {"key": 1}
  },
  "series": [
    {
      "start": "2026-09-29T14:02:11.482Z",
      "totals": {
        "requests": 1,
        "verdicts": {"passed": 1, "modified": 1, "blocked": 1, "cut": 1},
        "errors": 1,
        "input_tokens": 1,
        "output_tokens": 1,
        "cost": {
          "amount": "2.00",
          "currency": "USD",
          "estimated": false
        },
        "findings": {
          "secrets": 1,
          "personal_data": 1,
          "prompt_injection": 1,
          "illegal_content": 1,
          "moderation": 1,
          "tool_calls": 1,
          "custom_patterns": 1,
          "system_prompt_leak": 1,
          "grounding": 1
        },
        "organizations": 1,
        "users": 1,
        "models": {"key": 1},
        "providers": {"key": 1}
      }
    }
  ]
}

GET/summary/users

Totals for several users at oncePermission: read

Each user's summary by the day, as getSummary gives it for user_id, in the order of user_ids: a page of users' weeks in one call.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

fromquery, requiredstring (date-time)

The start of the period, included.

toquery, requiredstring (date-time)

The end of the period, excluded.

user_idsquery, requiredUserId[]

Up to 100 users.

Responses

200SummaryList

A summary for each user, minutes behind.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/summary/users?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&user_ids=user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "summary",
      "from": "2026-09-29T14:02:11.482Z",
      "to": "2026-09-29T14:02:11.482Z",
      "interval": "day",
      "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "user_id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "totals": {
        "requests": 1,
        "verdicts": {"passed": 1, "modified": 1, "blocked": 1, "cut": 1},
        "errors": 1,
        "input_tokens": 1,
        "output_tokens": 1,
        "cost": {
          "amount": "2.00",
          "currency": "USD",
          "estimated": false
        },
        "findings": {
          "secrets": 1,
          "personal_data": 1,
          "prompt_injection": 1,
          "illegal_content": 1,
          "moderation": 1,
          "tool_calls": 1,
          "custom_patterns": 1,
          "system_prompt_leak": 1,
          "grounding": 1
        },
        "organizations": 1,
        "users": 1,
        "models": {"key": 1},
        "providers": {"key": 1}
      },
      "series": [
        {
          "start": "2026-09-29T14:02:11.482Z",
          "totals": {
            "requests": 1,
            "verdicts": {"passed": 1, "modified": 1, "blocked": 1, "cut": 1},
            "errors": 1,
            "input_tokens": 1,
            "output_tokens": 1,
            "cost": {
              "amount": "2.00",
              "currency": "USD",
              "estimated": false
            },
            "findings": {
              "secrets": 1,
              "personal_data": 1,
              "prompt_injection": 1,
              "illegal_content": 1,
              "moderation": 1,
              "tool_calls": 1,
              "custom_patterns": 1,
              "system_prompt_leak": 1,
              "grounding": 1
            },
            "organizations": 1,
            "users": 1,
            "models": {"key": 1},
            "providers": {"key": 1}
          }
        }
      ]
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/summary/connections

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

fromquery, requiredstring (date-time)

The start of the period, included.

toquery, requiredstring (date-time)

The end of the period, excluded.

intervalquery"hour" | "day"

The width of each point in the series.

Responses

200ConnectionSummaryList

A summary for each connection tried, minutes behind.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/summary/connections?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "connection_summary",
      "connection_id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "health": "idle",
      "attempts": 1,
      "throttled": 1,
      "errors": 1,
      "fell_back": {"key": 1},
      "none_left": 1,
      "p50_ms": 1,
      "series": [{"start": "2026-09-29T14:02:11.482Z", "attempts": 1}]
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/query

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Body

Query

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/query' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-03T00:00:00Z",
  "filter": [{"field": "model", "op": "prefix", "value": "claude-"}],
  "compute": [
    {"name": "spend", "aggregation": "sum", "field": "cost"},
    {"name": "requests", "aggregation": "count"}
  ],
  "group_by": [{"field": "tags.feature", "limit": 2}],
  "interval": "day"
}'

Example response · 200

{
  "object": "query_result",
  "from": "2026-10-01T00:00:00.000Z",
  "to": "2026-10-03T00:00:00.000Z",
  "interval": "day",
  "complete_before": "2026-10-18T09:50:00.000Z",
  "groups": [
    {
      "by": {"tags.feature": "search"},
      "values": {"spend": "41.25", "requests": 3120},
      "series": [
        {
          "at": "2026-10-01T00:00:00.000Z",
          "values": {"spend": "20.50", "requests": 1540}
        },
        {
          "at": "2026-10-02T00:00:00.000Z",
          "values": {"spend": "20.75", "requests": 1580}
        }
      ]
    },
    {
      "by": {"tags.feature": "chat"},
      "values": {"spend": "8.50", "requests": 850},
      "series": [
        {
          "at": "2026-10-01T00:00:00.000Z",
          "values": {"spend": "4.00", "requests": 400}
        },
        {
          "at": "2026-10-02T00:00:00.000Z",
          "values": {"spend": "4.50", "requests": 450}
        }
      ]
    }
  ],
  "total": {
    "values": {"spend": "52.85", "requests": 4380},
    "series": [
      {
        "at": "2026-10-01T00:00:00.000Z",
        "values": {"spend": "26.00", "requests": 2150}
      },
      {
        "at": "2026-10-02T00:00:00.000Z",
        "values": {"spend": "26.85", "requests": 2230}
      }
    ]
  },
  "scanned_bytes": 13000000
}

GET/query/fields

The fields a query can name, and the tag keys the environment's requests carryPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Responses

200QueryFields

The registry, and the tag keys seen in the last 30 days.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/query/fields' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "query_fields",
  "fields": [
    {
      "name": "model",
      "kind": "dimension",
      "type": "string",
      "several": false
    },
    {
      "name": "guardrail",
      "kind": "dimension",
      "type": "enum",
      "several": true,
      "values": [
        "secrets",
        "personal_data",
        "prompt_injection",
        "illegal_content",
        "moderation",
        "tool_calls",
        "custom_patterns",
        "system_prompt_leak",
        "grounding"
      ]
    },
    {
      "name": "cost",
      "kind": "measure",
      "type": "money",
      "several": false
    }
  ],
  "tag_keys": ["feature", "team"]
}

Signals

Observations about users and organizations drawn from many requests.

GET/signals

List signalsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

organization_idqueryOrganizationId
user_idqueryUserId
statequerySignalState

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/signals' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "signal",
      "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "kind": "injection_attempts",
      "organization": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "score": 0.5,
      "window": {
        "from": "2026-09-29T14:02:11.482Z",
        "to": "2026-09-29T14:02:11.482Z"
      },
      "evidence": {
        "requests": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"],
        "features": {"key": 0.5}
      },
      "state": "open",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/signals/{id}

Get a signalPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredSignalId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/signals/signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "signal",
  "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "kind": "injection_attempts",
  "organization": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "score": 0.5,
  "window": {
    "from": "2026-09-29T14:02:11.482Z",
    "to": "2026-09-29T14:02:11.482Z"
  },
  "evidence": {
    "requests": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"],
    "features": {"key": 0.5}
  },
  "state": "open",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/signals/{id}/dismiss

Dismiss a signalPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

idpath, requiredSignalId

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/signals/signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/dismiss' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "signal",
  "id": "signal_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "kind": "injection_attempts",
  "organization": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "score": 0.5,
  "window": {
    "from": "2026-09-29T14:02:11.482Z",
    "to": "2026-09-29T14:02:11.482Z"
  },
  "evidence": {
    "requests": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"],
    "features": {"key": 0.5}
  },
  "state": "open",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

System prompts

The system prompts your app sends, declared so signals know them before traffic shows them. Only a keyed fingerprint of each is kept.

GET/system_prompts

List declared system promptsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/system_prompts' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "system_prompt",
      "id": "prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Acme",
      "fingerprint": "9f2c4e1ab07d5a31",
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/system_prompts

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

SystemPromptCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/system_prompts' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "You are Acme Assist. Answer questions about Acme orders.",
  "name": "Acme"
}'

Example response · 201

{
  "object": "system_prompt",
  "id": "prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "fingerprint": "9f2c4e1ab07d5a31",
  "created_at": "2026-09-29T14:02:11.482Z"
}

GET/system_prompts/{id}

Get a declared system promptPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredSystemPromptId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/system_prompts/prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "system_prompt",
  "id": "prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "fingerprint": "9f2c4e1ab07d5a31",
  "created_at": "2026-09-29T14:02:11.482Z"
}

DELETE/system_prompts/{id}

Withdraw a declared system promptPermission: manage

It stays usual only if traffic shows it to be.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredSystemPromptId

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/system_prompts/prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "system_prompt",
  "id": "prompt_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "fingerprint": "9f2c4e1ab07d5a31",
  "created_at": "2026-09-29T14:02:11.482Z"
}

Events

Notices of what happened in the environment.

GET/events

List eventsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

eventsqueryEventType[]

Only these event types.

created_afterquerystring (date-time)

Only objects created after this time.

created_beforequerystring (date-time)

Only objects created before this time.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/events' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "event": "organization.created",
      "data": {},
      "actor": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "environment_id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/events/{id}

Get an eventPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredEventId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/events/event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "event",
  "id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "event": "organization.created",
  "data": {},
  "actor": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "environment_id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "created_at": "2026-09-29T14:02:11.482Z"
}

Webhooks

Endpoints that receive events, and their deliveries.

GET/webhook_endpoints

List webhook endpointsPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "url": "https://example.com/alectura/webhooks",
      "events": ["organization.created"],
      "state": "enabled",
      "disabled_reason": null,
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/webhook_endpoints

Create a webhook endpointPermission: manage

The response is the only time the signing secret is shown.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

WebhookEndpointCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/alectura/webhooks",
  "events": ["user.suspended", "signal.detected"]
}'

Example response · 201

{
  "object": "webhook_endpoint",
  "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled",
  "disabled_reason": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z",
  "secret": "whsec_mJ3q8vXbT2kP9wR4sL7nY1cF6hD0gZ5aE8uB3oI2tK4"
}

GET/webhook_endpoints/{id}

Get a webhook endpointPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredWebhookEndpointId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "webhook_endpoint",
  "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled",
  "disabled_reason": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/webhook_endpoints/{id}

Update, enable or disable a webhook endpointPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredWebhookEndpointId

Body

WebhookEndpointUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled"
}'

Example response · 200

{
  "object": "webhook_endpoint",
  "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled",
  "disabled_reason": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/webhook_endpoints/{id}

Delete a webhook endpointPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredWebhookEndpointId

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "webhook_endpoint",
  "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled",
  "disabled_reason": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/webhook_endpoints/{id}/rotate_secret

Rotate an endpoint's signing secretPermission: manage

For 24 hours, deliveries carry a v1 signature for each of the old and new secrets.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

idpath, requiredWebhookEndpointId

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/rotate_secret' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "webhook_endpoint",
  "id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "url": "https://example.com/alectura/webhooks",
  "events": ["organization.created"],
  "state": "enabled",
  "disabled_reason": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z",
  "secret": "whsec_mJ3q8vXbT2kP9wR4sL7nY1cF6hD0gZ5aE8uB3oI2tK4"
}

POST/webhook_endpoints/{id}/test

Send a test deliveryPermission: manage

Delivers a webhook_endpoint.test event once, without retries, and returns the attempt.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredWebhookEndpointId
Idempotency-Keyheaderstring

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.

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/test' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "delivery",
  "id": "delivery_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "webhook_endpoint_id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "event_id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "event": "organization.created",
  "state": "pending",
  "attempts": [
    {
      "at": "2026-09-29T14:02:11.482Z",
      "status": 1,
      "duration_ms": 0.5,
      "error": null
    }
  ],
  "next_attempt_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z"
}

GET/webhook_endpoints/{id}/deliveries

List an endpoint's deliveriesPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredWebhookEndpointId
limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

statequeryDeliveryState

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/webhook_endpoints/webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/deliveries' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "delivery",
      "id": "delivery_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "webhook_endpoint_id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "event_id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "event": "organization.created",
      "state": "pending",
      "attempts": [
        {
          "at": "2026-09-29T14:02:11.482Z",
          "status": 1,
          "duration_ms": 0.5,
          "error": null
        }
      ],
      "next_attempt_at": "2026-09-29T14:02:11.482Z",
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/deliveries/{id}/retry

Retry a failed deliveryPermission: manage

Tries once more now, with the same delivery id.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

idpath, requiredDeliveryId

Responses

200Delivery

The delivery, with the new attempt.

410Error

The delivery's event has passed its retention.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/deliveries/delivery_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/retry' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "delivery",
  "id": "delivery_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "webhook_endpoint_id": "webhook_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "event_id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "event": "organization.created",
  "state": "pending",
  "attempts": [
    {
      "at": "2026-09-29T14:02:11.482Z",
      "status": 1,
      "duration_ms": 0.5,
      "error": null
    }
  ],
  "next_attempt_at": "2026-09-29T14:02:11.482Z",
  "created_at": "2026-09-29T14:02:11.482Z"
}

Alerts

Which of a connection's troubles, and limits nearly reached, are sent as events.

GET/alert_settings

Get which alerts are onPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/alert_settings' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "alert_settings",
  "on": ["throttled"],
  "throttled_minutes": 1
}

PATCH/alert_settings

Turn alerts on or offPermission: manage

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

Body

AlertSettingsUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/alert_settings' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on": ["throttled"], "throttled_minutes": 1}'

Example response · 200

{
  "object": "alert_settings",
  "on": ["throttled"],
  "throttled_minutes": 1
}

Jobs

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.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

ReplayCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/replays' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "match": {"organization": "globex"},
  "settings": {
    "routing": {
      "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
      "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
      "data_terms": {"retention": "zero", "training": "no"}
    },
    "retention": {"content": "none"},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 60}],
      "spend": [
        {"per": "user", "period": "day", "amount": "2.00"},
        {
          "per": "organization",
          "period": "month",
          "amount": "500.00",
          "action": "warn"
        }
      ]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {
        "action": "pseudonymize",
        "parts": ["user", "tool_result"],
        "kinds": ["email", "phone"],
        "exclusions": ["support@acme.example"]
      },
      "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
      "illegal_content": {"action": "warn"},
      "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
      "tool_calls": {
        "action": "cut",
        "allowed": [
          {"name": "read_file"},
          {
            "name": "send_email",
            "arguments": {
              "type": "object",
              "properties": {
                "to": {
                  "type": "string",
                  "pattern": "^[^@\\s]+@acme\\.example$"
                }
              },
              "required": ["to"]
            }
          }
        ]
      },
      "custom_patterns": {
        "action": "redact",
        "patterns": [
          {"name": "employee_id", "regex": "EMP-\\d{6}"},
          {
            "name": "codenames",
            "words": ["Falcon", "Project Heron"]
          }
        ]
      },
      "system_prompt_leak": {"action": "cut"},
      "grounding": {"action": "warn"}
    },
    "uninspected": "allow",
    "abuse": {"suspend_at": 0.9}
  },
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z"
}'

Example response · 202

{
  "object": "replay",
  "id": "replay_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "queued",
  "policy": {
    "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "match": {"organization": "globex"},
    "settings": {
      "routing": {
        "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
        "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
        "data_terms": {"retention": "zero", "training": "no"}
      },
      "retention": {"content": "none"},
      "limits": {
        "requests": [{"per": "user", "period": "minute", "amount": 60}],
        "spend": [
          {"per": "user", "period": "day", "amount": "2.00"},
          {
            "per": "organization",
            "period": "month",
            "amount": "500.00",
            "action": "warn"
          }
        ]
      },
      "guardrails": {
        "secrets": {"action": "redact"},
        "personal_data": {
          "action": "pseudonymize",
          "parts": ["user", "tool_result"],
          "kinds": ["email", "phone"],
          "exclusions": ["support@acme.example"]
        },
        "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
        "illegal_content": {"action": "warn"},
        "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
        "tool_calls": {
          "action": "cut",
          "allowed": [
            {"name": "read_file"},
            {
              "name": "send_email",
              "arguments": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^[^@\\s]+@acme\\.example$"
                  }
                },
                "required": ["to"]
              }
            }
          ]
        },
        "custom_patterns": {
          "action": "redact",
          "patterns": [
            {"name": "employee_id", "regex": "EMP-\\d{6}"},
            {
              "name": "codenames",
              "words": ["Falcon", "Project Heron"]
            }
          ]
        },
        "system_prompt_leak": {"action": "cut"},
        "grounding": {"action": "warn"}
      },
      "uninspected": "allow",
      "abuse": {"suspend_at": 0.9}
    }
  },
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "progress": 0.5,
  "result": {
    "requests": 1,
    "with_content": 1,
    "verdicts_changed": {"key": 1},
    "routing_changed": 1,
    "refused": {"key": 1},
    "findings_removed": 1,
    "samples": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"]
  },
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null
}

GET/replays/{id}

Get a replayPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredReplayId

Responses

200Replay

The replay, with its result once completed.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/replays/replay_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "replay",
  "id": "replay_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "queued",
  "policy": {
    "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "match": {"organization": "globex"},
    "settings": {
      "routing": {
        "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
        "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
        "data_terms": {"retention": "zero", "training": "no"}
      },
      "retention": {"content": "none"},
      "limits": {
        "requests": [{"per": "user", "period": "minute", "amount": 60}],
        "spend": [
          {"per": "user", "period": "day", "amount": "2.00"},
          {
            "per": "organization",
            "period": "month",
            "amount": "500.00",
            "action": "warn"
          }
        ]
      },
      "guardrails": {
        "secrets": {"action": "redact"},
        "personal_data": {
          "action": "pseudonymize",
          "parts": ["user", "tool_result"],
          "kinds": ["email", "phone"],
          "exclusions": ["support@acme.example"]
        },
        "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
        "illegal_content": {"action": "warn"},
        "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
        "tool_calls": {
          "action": "cut",
          "allowed": [
            {"name": "read_file"},
            {
              "name": "send_email",
              "arguments": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^[^@\\s]+@acme\\.example$"
                  }
                },
                "required": ["to"]
              }
            }
          ]
        },
        "custom_patterns": {
          "action": "redact",
          "patterns": [
            {"name": "employee_id", "regex": "EMP-\\d{6}"},
            {
              "name": "codenames",
              "words": ["Falcon", "Project Heron"]
            }
          ]
        },
        "system_prompt_leak": {"action": "cut"},
        "grounding": {"action": "warn"}
      },
      "uninspected": "allow",
      "abuse": {"suspend_at": 0.9}
    }
  },
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "progress": 0.5,
  "result": {
    "requests": 1,
    "with_content": 1,
    "verdicts_changed": {"key": 1},
    "routing_changed": 1,
    "refused": {"key": 1},
    "findings_removed": 1,
    "samples": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"]
  },
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null
}

POST/evidence_packs

Build an organization's evidence packPermission: manage

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

EvidencePackCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/evidence_packs' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z"
}'

Example response · 202

{
  "object": "evidence_pack",
  "id": "evidence_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "queued",
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null,
  "expires_at": null
}

GET/evidence_packs/{id}

Get an evidence packPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredEvidencePackId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/evidence_packs/evidence_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "evidence_pack",
  "id": "evidence_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "queued",
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null,
  "expires_at": null
}

GET/evidence_packs/{id}/download

Download a completed evidence packPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredEvidencePackId
formatquery"pdf" | "json"

pdf for a document to send, json for the same content as data.

Responses

200string

The pack.

410Error

The pack's files have been deleted.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/evidence_packs/evidence_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/download' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

POST/assessments

Start an assessmentPermission: manage

Returns an upload URL. Uploading the logs to it starts the assessment, which runs apart from live traffic and never touches its data.

Parameters

Alectura-EnvironmentheaderEnvironmentId

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-Keyheaderstring

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.

Body

AssessmentCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/assessments' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "format": "openai_chat_jsonl"}'

Example response · 201

{
  "object": "assessment",
  "id": "assessment_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "state": "awaiting_upload",
  "format": "openai_chat_jsonl",
  "upload": {
    "url": "https://example.com/alectura/webhooks",
    "method": "PUT",
    "max_bytes": 1,
    "expires_at": "2026-09-29T14:02:11.482Z"
  },
  "progress": {
    "step": "reading",
    "bytes_read": 1,
    "bytes_total": 1,
    "rows_read": 1,
    "accepted": 1,
    "rejected": {"key": 1},
    "users_seen": 1
  },
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null
}

GET/assessments/{id}

Get an assessmentPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredAssessmentId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/assessments/assessment_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "assessment",
  "id": "assessment_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "state": "awaiting_upload",
  "format": "openai_chat_jsonl",
  "upload": {
    "url": "https://example.com/alectura/webhooks",
    "method": "PUT",
    "max_bytes": 1,
    "expires_at": "2026-09-29T14:02:11.482Z"
  },
  "progress": {
    "step": "reading",
    "bytes_read": 1,
    "bytes_total": 1,
    "rows_read": 1,
    "accepted": 1,
    "rejected": {"key": 1},
    "users_seen": 1
  },
  "error": null,
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "completed_at": null
}

GET/assessments/{id}/report

Download a completed assessment's reportPermission: read

Parameters

Alectura-EnvironmentheaderEnvironmentId

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.

idpath, requiredAssessmentId
formatquery"pdf" | "json"

pdf for a document to send, json for the same content as data.

Responses

200string

The report.

410Error

The assessment's files have been deleted.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/assessments/assessment_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/report' \
  -H "Authorization: Bearer $ALECTURA_MANAGEMENT_KEY"

Example response · 200

{
  "object": "assessment_report",
  "assessment_id": "assessment_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "format": "openai_chat_jsonl",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "generated_at": "2026-09-29T14:02:11.482Z",
  "rows": {
    "read": 1,
    "accepted": 1,
    "unread": 1,
    "rejected": {"key": 1}
  },
  "users_analyzed": 1,
  "suspicious_users": 1,
  "tokens": {"total": 1, "suspicious": 1},
  "suspicious_token_share": 0.5,
  "estimated_cost": {"total": "2.00", "suspicious": "2.00"},
  "users": [
    {
      "user": "user_42",
      "organization": "acme",
      "plan": "pro",
      "score": 0.5,
      "requests": 1,
      "tokens": 1,
      "estimated_cost": "2.00",
      "signals": [
        {
          "kind": "injection_attempts",
          "score": 0.5,
          "lines": [1]
        }
      ]
    }
  ],
  "unavailable_signals": ["unavailable_signals"],
  "partial_signals": ["partial_signals"]
}

Team

The team, its members, projects and environments, on us.api only. Sessions only.

GET/team

Get the signed-in member's team

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/team' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "team",
  "id": "team_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/team

Rename the team

Body

TeamUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/team' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

Example response · 200

{
  "object": "team",
  "id": "team_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/team/members

List team members

Parameters

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

200MemberList

A page of members, invited ones included.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl 'https://us.api.alecturalabs.com/v1/team/members' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "member",
      "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "email": "ada@example.com",
      "name": "Acme",
      "role": "admin",
      "state": "invited",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

PATCH/team/members/{id}

Change a member's role

Parameters

idpath, requiredMemberId

Body

MemberUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/team/members/member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Example response · 200

{
  "object": "member",
  "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "email": "ada@example.com",
  "name": "Acme",
  "role": "admin",
  "state": "invited",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

DELETE/team/members/{id}

Remove a member

Locks the member out of every region within seconds, whatever their session says.

Parameters

idpath, requiredMemberId

Responses

Example request

curl -X DELETE 'https://us.api.alecturalabs.com/v1/team/members/member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "member",
  "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "email": "ada@example.com",
  "name": "Acme",
  "role": "admin",
  "state": "invited",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

POST/team/invitations

Invite someone to the team

Stytch emails a sign-in link. The invited member holds the role once they sign in.

Parameters

Idempotency-Keyheaderstring

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.

Body

InvitationCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/team/invitations' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com", "role": "admin"}'

Example response · 201

{
  "object": "member",
  "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "email": "ada@example.com",
  "name": "Acme",
  "role": "admin",
  "state": "invited",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/team/events

List the team's audit log

Who invited, changed the role of or removed each member, and when; kept for 400 days. Changes within an environment are its events.

Parameters

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/team/events' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "team_event",
      "id": "event_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "event": "member.invited",
      "data": {
        "object": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "email": "ada@example.com",
        "name": "Acme",
        "role": "admin",
        "state": "invited",
        "created_at": "2026-09-29T14:02:11.482Z",
        "updated_at": "2026-09-29T14:02:11.482Z"
      },
      "actor": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET/projects

List projects

Parameters

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/projects' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "project",
      "id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Acme",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/projects

Create a project

Parameters

Idempotency-Keyheaderstring

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.

Body

ProjectCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/projects' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

Example response · 201

{
  "object": "project",
  "id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/projects/{id}

Get a project

Parameters

idpath, requiredProjectId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/projects/project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "project",
  "id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/projects/{id}

Rename a project

Parameters

idpath, requiredProjectId

Body

ProjectUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/projects/project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

Example response · 200

{
  "object": "project",
  "id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/environments

List your team's environments, in every region

Parameters

limitqueryinteger

How many objects a page holds.

beforequerystring

An object id. Returns the page before it.

afterquerystring

An object id. Returns the page after it.

orderquery"asc" | "desc"

desc for newest first, asc for oldest first.

project_idqueryProjectId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/environments' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "environment",
      "id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "project_id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Acme",
      "region": "us",
      "production": false,
      "api_base_url": "https://eu.api.alecturalabs.com/v1",
      "gateway_base_url": "https://eu.gateway.alecturalabs.com",
      "created_at": "2026-09-29T14:02:11.482Z",
      "updated_at": "2026-09-29T14:02:11.482Z"
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

POST/environments

Create an environment in a region

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-Keyheaderstring

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.

Body

EnvironmentCreate

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/environments' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "project_id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "region": "us",
  "production": false
}'

Example response · 201

{
  "object": "environment",
  "id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "project_id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "region": "us",
  "production": false,
  "api_base_url": "https://eu.api.alecturalabs.com/v1",
  "gateway_base_url": "https://eu.gateway.alecturalabs.com",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

GET/environments/{id}

Get an environment

Parameters

idpath, requiredEnvironmentId

Responses

Example request

curl 'https://us.api.alecturalabs.com/v1/environments/env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT"

Example response · 200

{
  "object": "environment",
  "id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "project_id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "region": "us",
  "production": false,
  "api_base_url": "https://eu.api.alecturalabs.com/v1",
  "gateway_base_url": "https://eu.gateway.alecturalabs.com",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PATCH/environments/{id}

Rename an environment

Parameters

idpath, requiredEnvironmentId

Body

EnvironmentUpdate

Responses

Example request

curl -X PATCH 'https://us.api.alecturalabs.com/v1/environments/env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

Example response · 200

{
  "object": "environment",
  "id": "env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "project_id": "project_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Acme",
  "region": "us",
  "production": false,
  "api_base_url": "https://eu.api.alecturalabs.com/v1",
  "gateway_base_url": "https://eu.gateway.alecturalabs.com",
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

Feedback

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-Keyheaderstring

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.

Body

FeedbackCreate

Responses

201Feedback

The feedback, with where to send its files.

4XX

An error: see Errors

5XX

A service is unavailable: see Errors

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/feedback' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "page": "https://app.alecturalabs.com/env_01J9ZQ6V8D3K4M5N6P7Q8R9S0T/requests",
  "message": "The export button does nothing on this page.",
  "screenshot": {"content_type": "image/png", "bytes": 482113}
}'

Example response · 201

{
  "object": "feedback",
  "id": "feedback_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "created_at": "2026-09-29T14:02:11.482Z",
  "uploads": {
    "screenshot": {
      "url": "https://example.com/alectura/webhooks",
      "method": "PUT",
      "content_type": "image/png",
      "bytes": 1,
      "expires_at": "2026-09-29T14:02:11.482Z"
    },
    "recording": {
      "url": "https://example.com/alectura/webhooks",
      "method": "PUT",
      "content_type": "image/png",
      "bytes": 1,
      "expires_at": "2026-09-29T14:02:11.482Z"
    }
  }
}

POST/dashboard_errors

Report an error the dashboard showed

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.

Body

DashboardErrorReport

Responses

Example request

curl -X POST 'https://us.api.alecturalabs.com/v1/dashboard_errors' \
  -H "Authorization: Bearer $ALECTURA_SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "page": "/:environmentId/requests/:id",
  "call": "GET /requests/{id}/content",
  "kind": "unreadable",
  "status": 200,
  "build": "index-C3kZ0d1q.js"
}'

Webhook events

Each event is delivered to your endpoints as a signed POST with this body.

organization.createdEvent & object

An organization was created, by the API or by the first request that named it.

organization.updatedEvent & object

An organization's name or metadata changed.

organization.deletedEvent & object

An organization was deleted. Its key is already destroyed.

user.createdEvent & object

A user was created, by the API or by the first request that named it.

user.updatedEvent & object

A user's name or metadata changed.

system_prompt.createdEvent & object

A system prompt was declared as the app's own.

system_prompt.deletedEvent & object

A declared system prompt was withdrawn.

user.suspendedEvent & object

A user was suspended, by a team member, a key or a policy.

user.unsuspendedEvent & object

A user's last suspension in force was lifted or expired, so the gateway serves them again. Ending one that another outlasts fires nothing.

organization.suspendedEvent & object

An organization was suspended, by a team member or a key. No policy suspends an organization: `abuse.suspend_at` suspends users only.

organization.unsuspendedEvent & object

An organization's last suspension in force was lifted or expired, so the gateway serves it again. Ending one that another outlasts fires nothing.

signal.detectedEvent & object

A signal job observed something about a user or organization.

policy.createdEvent & object

A policy was created.

policy.updatedEvent & object

A policy changed, making a new version.

policy.deletedEvent & object

A policy was deleted.

connection.createdEvent & object

A connection was created, as a draft.

connection.updatedEvent & object

A connection changed, including its state.

connection.deletedEvent & object

A connection was deleted.

api_key.createdEvent & object

An API key was created. The event never carries the secret.

api_key.updatedEvent & object

An API key was renamed, disabled, enabled, rotated or given an expiry.

api_key.revokedEvent & object

An API key was revoked.

content_store.updatedEvent & object

The content store was set, or became active when its test passed.

content_store.deletedEvent & object

The content store was removed.

webhook_endpoint.createdEvent & object

A webhook endpoint was added.

webhook_endpoint.updatedEvent & object

A webhook endpoint was changed, enabled, disabled by the team, or had its secret rotated.

webhook_endpoint.deletedEvent & object

A webhook endpoint was deleted. It goes to the other endpoints.

webhook_endpoint.disabledEvent & object

An endpoint was disabled because a delivery to it failed five times. It goes to the other endpoints.

webhook_endpoint.testEvent & object

A test delivery, sent only to the endpoint being tested.

request.blockedEvent & object

A policy refused a request. Suspensions count.

request.cutEvent & object

A guardrail cut a response.

request.content_readEvent & object

Someone read a request's content or an attachment.

limit.threshold_crossedEvent & object

A limit passed 80% or 95% of its amount, a block limit started refusing, or use passed a warn limit.

replay.completedEvent & object

A replay finished.

replay.failedEvent & object

A replay failed.

evidence_pack.completedEvent & object

An evidence pack is ready to download.

evidence_pack.failedEvent & object

An evidence pack failed.

assessment.completedEvent & object

An assessment's report is ready.

assessment.failedEvent & object

An assessment failed.

alert.raisedEvent & object

A connection started throttling, falling back or running out of fallbacks, with that alert on.

alert.clearedEvent & object

A raised alert stopped: its connection went 10 minutes without it.

Schemas

Error

coderequiredstring
messagerequiredstring
errorsobject[]

Each item

fieldrequiredstring

A dotted path into the body, such as settings.routing.regions; for connection_test_failed, the check that failed, such as credential or model:gpt-5.5.

coderequiredstring
messagestring
request_idrequiredRequestId

ListMetadata

beforerequiredstring | null
afterrequiredstring | null

Timestamp

string (date-time)

Money

amountrequiredDecimal
currencyrequired"USD"
estimatedrequiredboolean

True for list prices from the pinned price map, rather than a provider's bill.

Decimal

string

ExternalId

Your own identifier, as the Alectura-* headers carry it.

string

Metadata

map<string, string>

Actor

Who made a change.

typerequired"api_key" | "member" | "organization" | "policy" | "system"

organization is its admin, in a portal session.

idrequiredstring | null

The key's, member's, organization's or policy's id; null for the system.

Example

{"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"}

Region

A region Alectura runs in.

"us" | "eu" | "au"

ProviderRegion

Where a provider processes a request. global is for endpoints that promise no region, such as Bedrock's global. inference profiles.

"us" | "eu" | "au" | "apac" | "global"

OrganizationId

string

UserId

string

OrganizationMembershipId

string

SuspensionId

string

SystemPromptId

string

PolicyId

string

ConnectionId

string

ApiKeyId

string

RequestId

string

ConversationId

string

FindingId

string

DispositionId

string

SignalId

string

EventId

string

WebhookEndpointId

string

DeliveryId

string

ReplayId

string

EvidencePackId

string

AssessmentId

string

TeamId

string

MemberId

string

ProjectId

string

FeedbackId

string

EnvironmentId

string

Ref

A reference to an organization or user, with your identifier.

idrequiredstring
external_idrequiredExternalId

Example

{"id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T", "external_id": "acme"}

Organization

objectrequired"organization"
idrequiredOrganizationId
external_idrequiredExternalId
namerequiredstring | null
metadatarequiredMetadata
planrequiredstring | null

The plan named by its latest request that sent Alectura-Plan; null until one does.

suspendedrequiredboolean
staterequired"active" | "deleting"
first_seen_atrequiredstring (date-time) | null
last_seen_atrequiredstring (date-time) | null
created_atrequiredTimestamp
updated_atrequiredTimestamp

OrganizationUpdate

namestring | null
metadataMetadata

User

objectrequired"user"
idrequiredUserId
external_idrequiredExternalId
namerequiredstring | null
metadatarequiredMetadata
suspendedrequiredboolean
signalsUserSignal[]

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.

first_seen_atrequiredstring (date-time) | null
last_seen_atrequiredstring (date-time) | null
created_atrequiredTimestamp
updated_atrequiredTimestamp

UserSignal

An open signal on a user, as the users list shows it. getSignal has the rest.

idrequiredSignalId
kindrequiredstring

What was observed, as the signal's kind.

scorerequirednumber

UserUpdate

namestring | null
metadataMetadata

RelatedUserList

objectrequired"list"
datarequiredobject[]

Each item

objectrequired"related_user"
userrequiredRef
shared_fingerprintsrequiredinteger

How many prompt templates both users' requests share.

list_metadatarequiredListMetadata

Suspension

objectrequired"suspension"
idrequiredSuspensionId
organizationrequiredRef | null

Set when an organization is suspended.

userrequiredRef | null

Set when a user is suspended.

reasonrequiredstring

A short reason, such as signals for one a policy made.

noterequiredstring | null
created_byrequiredActor
created_atrequiredTimestamp
expires_atrequiredstring (date-time) | null
lifted_atrequiredstring (date-time) | null
lifted_byrequiredActor | null

SuspensionCreate

Names exactly one of organization_id and user_id.

organization_idOrganizationId
user_idUserId
reasonrequiredstring
notestring
expires_atTimestamp

Example

{
  "user_id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "reason": "abuse",
  "note": "Scraping answers at volume.",
  "expires_at": "2026-10-09T00:00:00.000Z"
}

SystemPrompt

A system prompt you declared as your app's own. Its text isn't kept.

objectrequired"system_prompt"
idrequiredSystemPromptId
namerequiredstring | null
fingerprintrequiredstring

The keyed hash of the prompt's text, as requests' prompts are hashed.

created_atrequiredTimestamp

SystemPromptCreate

textrequiredstring

The prompt, exactly as the app sends it, several system blocks joined by line breaks. Only its fingerprint is kept.

namestring | null

Policy

objectrequired"policy"
idrequiredPolicyId
namerequiredstring
descriptionrequiredstring | null
ownerrequiredOwner

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.

matchrequiredMatch
settingsrequiredSettings
versionrequiredinteger
created_atrequiredTimestamp
updated_atrequiredTimestamp

Example

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "owner": {"type": "environment"},
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

PolicyCreate

namerequiredstring
descriptionstring
ownerOwner

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).

matchrequiredMatch
settingsrequiredSettings

Example

{
  "name": "Free plan",
  "description": "Tighter limits and a cheaper model for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"models": {"only": ["gpt-5-mini"]}},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact"},
      "personal_data": {"action": "pseudonymize"}
    }
  }
}

PolicyUpdate

namestring
descriptionstring | null
matchMatch

Replaces the whole match, never merges into it: a field left out no longer selects.

settingsSettings

Example

{
  "settings": {
    "limits": {
      "spend": [{"per": "user", "period": "day", "amount": "1.00"}]
    }
  }
}

PolicyVersion

objectrequired"policy_version"
policy_idrequiredPolicyId
versionrequiredinteger
namerequiredstring
matchrequiredMatch
settingsrequiredSettings
deletedrequiredboolean

True for the version that deleted the policy.

created_byrequiredActor
created_atrequiredTimestamp

Match

Selects requests by their Alectura-* headers. Every field given must hold, and an omitted field matches anything. {} matches every request.

organizationMatchValue
userMatchValue
planMatchValue
tagsmap<string, MatchValue>

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.

ExternalId | ExternalId[] | null

Uninspected

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_atnumber

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.

connectionsConnectionAllowList | ("own" | "environment")[]

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.

regionsRegionAllowList | ProviderRegion[]

Where a provider may process a request. An effective policy that leaves none refuses every request.

modelsModelAllowList | string[]

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_termsobject

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.

Example

{
  "regions": {"add": {"eu": {"rank": 1}}, "only": ["eu"]},
  "models": {"only": ["claude-sonnet-5-5", "claude-haiku-4-5"]},
  "data_terms": {"retention": "zero", "training": "no"}
}

ModelAllowList

addmap<string, Rank>
onlystring[]
removestring[]

Rank

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.

rankinteger | 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_tokensinteger

Lowers a request's maximum output to this, and sets it when the request doesn't. The lowest wins.

requestsobject[]

Each item

perrequiredLimitScope
periodrequired"minute" | "day"
amountrequiredinteger
actionLimitAction
tagsLimitTags
tokensobject[]

Input and output tokens together.

Each item

perrequiredLimitScope
periodrequired"minute" | "day"
amountrequiredinteger
actionLimitAction
tagsLimitTags
spendobject[]

Estimated cost at list prices, in USD.

Each item

perrequiredLimitScope
periodrequired"day" | "week" | "month"
amountrequiredDecimal
actionLimitAction
tagsLimitTags

Example

{
  "requests": [{"per": "user", "period": "minute", "amount": 60}],
  "spend": [
    {"per": "user", "period": "day", "amount": "2.00"},
    {
      "per": "organization",
      "period": "month",
      "amount": "500.00",
      "action": "warn"
    }
  ]
}

LimitAction

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.

map<string, MatchValue>

Example

{"feature": "search"}

LimitScope

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.

Example

{
  "secrets": {"action": "redact"},
  "personal_data": {
    "action": "pseudonymize",
    "parts": ["user", "tool_result"],
    "kinds": ["email", "phone"],
    "exclusions": ["support@acme.example"]
  },
  "prompt_injection": {"action": "cut", "parts": ["tool_result"]},
  "illegal_content": {"action": "warn"},
  "moderation": {"action": "block", "kinds": ["hate", "harassment"]},
  "tool_calls": {
    "action": "cut",
    "allowed": [
      {"name": "read_file"},
      {
        "name": "send_email",
        "arguments": {
          "type": "object",
          "properties": {
            "to": {
              "type": "string",
              "pattern": "^[^@\\s]+@acme\\.example$"
            }
          },
          "required": ["to"]
        }
      }
    ]
  },
  "custom_patterns": {
    "action": "redact",
    "patterns": [
      {"name": "employee_id", "regex": "EMP-\\d{6}"},
      {
        "name": "codenames",
        "words": ["Falcon", "Project Heron"]
      }
    ]
  },
  "system_prompt_leak": {"action": "cut"},
  "grounding": {"action": "warn"}
}

EffectiveGuardrailSettings

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.

secretsSecretsGuardrail[]
personal_dataPersonalDataGuardrail[]
prompt_injectionInjectionGuardrail[]
illegal_contentIllegalContentGuardrail[]
moderationModerationGuardrail[]
tool_callsToolCallsGuardrail[]
custom_patternsCustomPatternsGuardrail[]
system_prompt_leakSystemPromptLeakGuardrail[]
groundingGroundingGuardrail[]

SecretsGuardrail

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.

actionrequired"warn" | "redact" | "block" | "record"
modeGuardrailMode
partsParts

PersonalDataGuardrail

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.

actionrequired"warn" | "pseudonymize" | "redact" | "block" | "record"
modeGuardrailMode
partsParts
kinds("email" | "phone" | "card_number" | "iban" | "ip_address" | "national_id" | "person_name" | "street_address" | "date_of_birth" | "passport_number" | "driver_license_number" | "bank_account_number")[]

Default all. card_number covers the published test card numbers exclude_test_cards lists, found as test_card_number unless it is set.

exclusionsstring[]

Exact values never treated as personal data, such as your support address.

exclude_test_cardsboolean

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.

actionrequired"warn" | "cut" | "flag"
modeGuardrailMode
partsParts
tier"local" | "model" | "decision"

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.

actionrequired"warn" | "block" | "flag"
modeGuardrailMode
partsParts
kinds("violent_crimes" | "non_violent_crimes" | "sex_crimes" | "child_sexual_exploitation" | "weapons")[]

Default all.

tier"local" | "model" | "decision"

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.

actionrequired"warn" | "block"
modeGuardrailMode
partsParts
kinds("hate" | "harassment" | "self_harm" | "sexual" | "violence")[]

Default all.

tier"local" | "model" | "decision"

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.

actionrequired"warn" | "redact" | "block"
partsParts
patternsrequiredCustomPattern[]

At most 30 regexes, which compile to at most 128 KiB together, and 10,000 words in all the lists.

CustomPattern

namerequiredstring

The kind of its findings, and the label of its redactions. Unique in a policy.

regexstring

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.

wordsstring[]

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).

actionrequired"warn" | "cut"
allowedAllowedTool[]

The tools the answer may call; a call that one entry allows is allowed. Unset: any tool denied doesn't name. Empty: none.

deniedToolName[]

Tools the answer may never call, even where allowed names them.

Example

{
  "action": "cut",
  "allowed": [
    {"name": "mcp__github__*"},
    {
      "name": "send_email",
      "arguments": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^[^@\\s]+@acme\\.example$"
          }
        },
        "required": ["to"]
      }
    }
  ],
  "denied": ["mcp__github__delete_repo"]
}

AllowedTool

namerequiredToolName
argumentsmap<string, any> | boolean

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.

Part[]

Part

output is the provider's answer, streamed or not; the rest are the request's input.

"system" | "user" | "assistant" | "tool_call" | "tool_result" | "output"

EffectivePolicy

objectrequired"effective_policy"
identityrequiredobject

Fields

organizationrequiredstring | null
userrequiredstring | null
planrequiredstring | null
tagsmap<string, ExternalId>

The tags given; absent when none were.

policiesrequiredPolicyRef[]

The matching policies, at their current versions.

settingsrequiredEffectiveSettings

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.

sourcesrequiredmap<string, PolicyId[]>

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_teamstring[]

Only in a portal session: the settings, by dotted path, that the team's policies decide, alone or with the organization's own.

tracerequiredobject

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.

Fields

routing.modelsrequiredTrace
routing.regionsrequiredTrace
routing.connectionsrequiredTrace
candidatesobject[]

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.

Each item

positionrequiredinteger
connectionrequiredConnectionId
modelrequiredstring

The model it would be sent, as asked, or a fallback by the id its connection knows it by.

model_rankrequiredinteger | null

0 for the model asked for; a fallback's rank, or null for one without.

regionrequiredProviderRegion
region_rankrequiredinteger | null
rankrequiredinteger | null

Trace

seedrequiredRankedMember[]
stepsrequiredobject[]

Each item

policyrequiredPolicyId
addmap<string, Rank>
onlystring[]
removestring[]
resultRankedMember[]

What's left, in the order it's tried.

RankedMember

memberrequiredstring
rankrequiredinteger | null

0 for what the request asks for, a policy's number, or null for none.

PolicyRef

idrequiredPolicyId
versionrequiredinteger

Provider

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.

"openai" | "anthropic" | "bedrock" | "bedrock_mantle" | "gemini" | "openrouter" | "azure" | "vertex_ai" | "vercel_ai_gateway" | "simulator"

ConnectionState

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"
hintrequiredstring

The last four characters of a key, a role's name, or a service account's email.

Owner

Who owns the connection or policy.

object | object

Connection

objectrequired"connection"
idrequiredConnectionId
namerequiredstring
providerrequiredProvider
ownerrequiredOwner
base_urlrequired"https://api.openai.com/v1" | "https://eu.api.openai.com/v1" | "https://us.api.openai.com/v1" | "https://au.api.openai.com/v1" | "https://api.anthropic.com" | "https://generativelanguage.googleapis.com" | "https://openrouter.ai/api/v1" | "https://eu.openrouter.ai/api/v1" | "https://us.openrouter.ai/api/v1" | "https://ai-gateway.vercel.sh/v1" | null

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_regionrequiredstring | 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_resourcerequiredstring | null

For Azure OpenAI, the resource whose endpoint is https://{azure_resource}.openai.azure.com.

azure_regionrequiredstring | null

For Azure OpenAI, the resource's region.

vertex_projectrequiredstring | null

For Vertex AI, the Google Cloud project's id.

vertex_locationrequiredstring | null

For Vertex AI, where the project's models run, global, us, eu or a region.

openai_projectrequiredstring | null

For Bedrock mantle, the project its requests are made in, or null for your AWS account's default project.

regionrequiredProviderRegion

Where the endpoint promises to process requests. Derived, never set.

modelsrequiredstring[]

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.

application_inference_profilesrequiredApplicationInferenceProfiles
data_termsrequiredDataTerms
credentialrequiredCredentialHint | null

Null for a simulator connection that names no key.

aws_external_idrequiredstring | null

For an aws_role credential, the external id the role's trust policy must require.

staterequiredConnectionState
cooling_down_untilrequiredstring (date-time) | null

Set while repeated failures with a model keep the connection last for it.

created_atrequiredTimestamp
updated_atrequiredTimestamp

Example

{
  "object": "connection",
  "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "OpenAI EU",
  "provider": "openai",
  "owner": {"type": "environment"},
  "base_url": "https://eu.api.openai.com/v1",
  "aws_region": null,
  "inference_profile": null,
  "azure_resource": null,
  "azure_region": null,
  "vertex_project": null,
  "vertex_location": null,
  "openai_project": null,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "application_inference_profiles": {},
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "hint": "Qk3x"},
  "aws_external_id": null,
  "state": "draft",
  "cooling_down_until": null,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

ConnectionCreate

namerequiredstring

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.

providerrequiredProvider
ownerOwner

Default the environment.

base_url"https://api.openai.com/v1" | "https://eu.api.openai.com/v1" | "https://us.api.openai.com/v1" | "https://au.api.openai.com/v1" | "https://api.anthropic.com" | "https://generativelanguage.googleapis.com" | "https://openrouter.ai/api/v1" | "https://eu.openrouter.ai/api/v1" | "https://us.openrouter.ai/api/v1" | "https://ai-gateway.vercel.sh/v1"
aws_regionstring
inference_profile"us" | "eu" | "apac" | "au" | "global" | null

Required for Azure OpenAI.

openai_projectstring

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.

azure_resourcestring
azure_regionstring
vertex_projectstring
vertex_locationstring

Default global.

modelsrequiredstring[]
application_inference_profilesApplicationInferenceProfiles
data_termsDataTerms
credentialCredential

Required, except for the simulator, which reaches no provider and needs no key.

Example

{
  "name": "OpenAI EU",
  "provider": "openai",
  "base_url": "https://eu.api.openai.com/v1",
  "models": ["gpt-5", "gpt-5-mini"],
  "data_terms": {"retention": "zero", "training": "no"},
  "credential": {"type": "api_key", "api_key": "sk-proj-…"}
}

ApplicationInferenceProfiles

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

map<string, string>

Example

{
  "us.anthropic.claude-haiku-4-5-20251001-v1:0": "arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/a1b2c3d4e5f6"
}

ConnectionTest

objectrequired"connection_test"
connection_idrequiredConnectionId
passedrequiredboolean

True when every check passed.

checksrequiredobject[]

Each item

namerequiredstring

What was checked, such as credential, model:gpt-5, profile: and a model id, stream or usage.

passedrequiredboolean
reasonrequiredstring | null

Why it failed, such as invalid_credential, model_unavailable, invalid_stream, missing_usage, profile_unreadable, profile_mismatch or region_not_allowed.

messagerequiredstring | null
upstream_statusinteger | null

The provider's HTTP status, when it answered.

created_atrequiredTimestamp

ContentStore

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"
bucketrequiredstring
regionrequiredstring
prefixrequiredstring

What every key starts with: empty, or ending in /.

role_arnrequiredstring
external_idrequiredstring

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.

created_atrequiredTimestamp
updated_atrequiredTimestamp

ContentStoreSet

bucketrequiredstring
regionrequiredstring

The bucket's AWS region, which must be in the environment's region, so content never leaves it.

prefixstring
role_arnrequiredstring

ContentStoreTest

objectrequired"content_store_test"
passedrequiredboolean
messagerequiredstring | null

Why it failed, such as the role that couldn't be assumed or the key that couldn't be written.

content_storerequiredContentStore

ApiKeyType

Sending keys call the gateway; management keys call this API.

"sending" | "management"

ApiKeyState

"active" | "disabled" | "expired" | "revoked"

Permission

"send" | "read" | "read_content" | "manage"

ApiKey

objectrequired"api_key"
idrequiredApiKeyId
namerequiredstring
typerequiredApiKeyType
permissionsrequiredPermission[]

send alone for a sending key; any of them for a management key, where send lets it create and rotate sending keys.

labelrequiredstring

The key with all but its prefix and last six characters masked.

staterequiredApiKeyState
expires_atrequiredstring (date-time) | null
previous_secret_expires_atrequiredstring (date-time) | null

After a rotation, when the old secret stops working; null once it has, or once the key is no longer active.

created_byrequiredActor
created_atrequiredTimestamp
updated_atrequiredTimestamp

ApiKeyWithSecret

ApiKey & object

ApiKeyCreate

namerequiredstring
typeApiKeyType

Default sending.

permissionsPermission[]

For a management key, and none the caller lacks; a sending key always has send alone. send lets a management key create and rotate sending keys.

expires_atTimestamp

Example

{"name": "Production servers"}

ApiKeyUpdate

namestring
state"active" | "disabled"
expires_atstring (date-time) | null

PortalFeature

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.

"regions" | "models" | "connections" | "data_terms" | "retention" | "limits" | "guardrails" | "model_tier" | "uninspected"

PortalSessionCreate

organization_idrequiredOrganizationId
featuresPortalFeature[]

Default both.

setting_groupsPortalSettingGroup[]

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.

Example

{
  "organization_id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "features": ["policies"],
  "setting_groups": ["regions", "guardrails"]
}

PortalSession

objectrequired"portal_session"
urlrequiredstring (uri)

The page, with the session's token after #, so it never reaches a server log. Treat it as a secret.

organization_idrequiredOrganizationId
featuresrequiredPortalFeature[]
setting_groupsrequiredPortalSettingGroup[]

Empty without policies.

expires_atrequiredTimestamp

Verdict

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.

"passed" | "modified" | "blocked" | "cut"

Guardrail

"secrets" | "personal_data" | "prompt_injection" | "illegal_content" | "moderation" | "tool_calls" | "custom_patterns" | "system_prompt_leak" | "grounding"

ContentVersion

What the client sent; what the provider received; what the provider sent back; what the client received.

"client_request" | "provider_request" | "provider_response" | "client_response"

Request

objectrequired"request"
idrequiredRequestId
staterequired"pending" | "completed" | "interrupted"

pending while the request is still running; interrupted if its end never arrived because the gateway task serving it stopped.

created_atrequiredTimestamp
completed_atrequiredstring (date-time) | null
organizationrequiredRef | null
userrequiredRef | null
planrequiredstring | null
conversation_idrequiredConversationId | null
tagsrequiredmap<string, ExternalId>

The request's Alectura-Tags, by key in lowercase (gateway.md, Tags); empty when it sent none, or when it was refused before its tags were read.

api_key_idrequiredApiKeyId
endpointrequired"openai.chat_completions" | "openai.responses" | "anthropic.messages" | "gemini.generate_content" | "bedrock.converse" | "openai.embeddings" | "anthropic.count_tokens" | null

Null for a request refused before its path named an endpoint.

modelrequiredstring | 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.

streamrequiredboolean
statusrequiredinteger | null

The HTTP status the client received; null while pending.

verdictrequiredVerdict
refusalrequiredobject | null

Our refusal or cut, if there was one.

connectionrequiredConnectionRef | null

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.

attemptsrequiredobject[]

Every connection tried, in order.

Each item

connectionrequiredConnectionRef
modelrequiredstring | null

The fallback model it was sent, by the id its connection knows it by; null for the model the request asked for.

started_atrequiredTimestamp
statusrequiredinteger | null

The provider's HTTP status; null if it never answered.

errorrequiredstring | 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.

duration_msrequirednumber
policiesrequiredPolicyRef[]

The policies that matched, at their versions then.

findingsrequiredFinding[]
coveragerequiredobject[]

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.

Each item

blockrequiredinteger
partrequiredPart
modalityrequired"text" | "image" | "audio" | "video" | "file" | "reasoning"
inspected_byrequiredGuardrail[]
reasonrequired"images_uninspected" | "audio_uninspected" | "video_uninspected" | "files_uninspected" | "uninspectable" | "encrypted" | "not_selected" | "refused_first" | null

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.

checksrequiredModelCheck[]

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.

usagerequiredUsage | null
costrequiredMoney | null
timingsrequiredobject

Fields

overhead_msrequirednumber

Time the gateway added, excluding the provider.

first_byte_msrequirednumber | null
duration_msrequirednumber | null
first_token_overhead_msrequirednumber | null

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_msrequirednumber | 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.

guardrailsrequiredobject[]

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.

Each item

guardrailrequiredGuardrail
request_msrequirednumber

On the request, before the provider call, and so part of overhead_ms.

alongside_msrequirednumber | 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_msrequirednumber | 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.

contentrequiredobject

Fields

retainedrequiredboolean
retentionrequired"none" | "team" | "7d" | "30d" | "90d" | "365d"
expires_atrequiredstring (date-time) | null
reasonrequired"retention_none" | "not_sent" | "unanswered" | null

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.

ModelCheck

guardrailrequiredGuardrail
blockrequiredinteger
modelrequiredstring | null

The model asked, by its connection's id for it, or gliner_multi_pii-v1 for personal data's ner tier; null when unserved or not_asked.

connectionrequiredConnectionRef | null
outcomerequired"flagged" | "passed" | "unreadable" | "failed" | "timed_out" | "unserved" | "not_asked"

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.

duration_msrequirednumber
input_tokensrequiredinteger
output_tokensrequiredinteger
costrequiredMoney | null

At the model's list price; your provider bills it, outside the request's cost.

Usage

input_tokensrequiredinteger

Input tokens not read from or written to the cache.

output_tokensrequiredinteger

Output tokens, reasoning included.

cache_read_input_tokensrequiredinteger
cache_creation_input_tokensrequiredinteger
reasoning_tokensrequiredinteger | null
estimatedrequiredboolean

True when the provider reported no usage and the gateway counted.

rawrequiredobject | null

The provider's usage object, as it sent it.

Finding

objectrequired"finding"
idrequiredFindingId
guardrailrequiredGuardrail
kindrequiredstring

What the detector found, such as aws_access_key, email, instruction_override, weapons or unsupported_claim.

actionrequired"warn" | "redact" | "pseudonymize" | "block" | "cut"

warn recorded the finding and changed nothing.

blockrequiredinteger
partrequiredPart

ContentRead

objectrequired"content_read"
request_idrequiredRequestId
versionrequiredContentVersion | null
attachmentrequiredstring | null

The attachment's hash, when one was read.

readerrequiredActor

FindingsSummary

objectrequired"findings_summary"
fromrequiredTimestamp
torequiredTimestamp
groupsrequiredobject[]

Each item

guardrailrequiredGuardrail
kindrequiredstring
actionrequired"warn" | "redact" | "pseudonymize" | "block" | "cut"
countrequiredinteger
requestsrequiredinteger

Distinct requests, each counted once however often a block was resent. A request with two kinds is in both groups, so these don't add up to requests.

samplesrequiredRequestId[]
requestsrequiredinteger

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_actionrequiredmap<string, integer>

Each action's requests with any of these findings under it, counted as requests is.

Disposition

objectrequired"disposition"
idrequiredDispositionId
finding_idrequiredFindingId
labelrequired"false_positive" | "confirmed" | "not_sure"
noterequiredstring | null
created_byrequiredActor
created_atrequiredTimestamp

DispositionCreate

labelrequired"false_positive" | "confirmed" | "not_sure"
notestring

Totals

requestsrequiredinteger
verdictsrequiredobject

Fields

passedrequiredinteger
modifiedrequiredinteger
blockedrequiredinteger
cutrequiredinteger
errorsrequiredinteger

Requests whose provider failed.

input_tokensrequiredinteger
output_tokensrequiredinteger
costrequiredMoney
findingsrequiredobject

Fields

secretsrequiredinteger
personal_datarequiredinteger
prompt_injectionrequiredinteger
illegal_contentrequiredinteger
moderationrequiredinteger
tool_callsrequiredinteger
custom_patternsrequiredinteger
system_prompt_leakrequiredinteger
groundingrequiredinteger
organizationsrequiredinteger

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.

usersrequiredinteger

Distinct users, counted as organizations is.

modelsrequiredmap<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.

providersrequiredmap<string, integer>

The requests a provider answered, by that provider.

ConnectionSummary

objectrequired"connection_summary"
connection_idrequiredConnectionId
healthrequired"idle" | "failing" | "throttled" | "healthy"

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.

attemptsrequiredinteger
throttledrequiredinteger

Attempts it answered 429.

errorsrequiredinteger

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_backrequiredmap<string, integer>

Failed attempts, 429s included, after which the request tried another connection, by that one.

none_leftrequiredinteger

Failed attempts, 429s included, after which the request had no connection left to try.

p50_msrequiredinteger | 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.

seriesrequiredobject[]

Its attempts in each period of the interval asked for that overlaps the window, the whole period, as a summary's series counts them.

Each item

startrequiredTimestamp
attemptsrequiredinteger

Query

dataset"requests"
fromrequiredstring (date-time)

The start of the period, included. A request is in the period its created_at is in.

torequiredstring (date-time)

The end of the period, excluded. At most 400 days after from.

filterQueryCondition[]

Conditions that must all hold.

computerequiredQueryCompute[]
group_byQueryGroupBy[]
interval"hour" | "day" | "week" | "month"

The width of each point, on UTC boundaries; a week starts on Monday. Absent for totals only. Groups times points is at most 10,000.

QueryField

A field of the registry, or tags. and a tag key.

string

QueryValue

A value of the field's type. Money is a decimal string in USD.

string | integer | boolean | null

QueryCondition

fieldrequiredQueryField
oprequired"eq" | "ne" | "in" | "not_in" | "prefix" | "exists" | "missing" | "gt" | "gte" | "lt" | "lte"

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.

valueQueryValue
valuesQueryValue[]

QueryCompute

namerequiredstring

The key of this value in the answer.

aggregationrequired"count" | "sum" | "min" | "max" | "avg" | "distinct" | "p50" | "p95" | "p99"

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.

fieldQueryField

QueryGroupBy

fieldrequiredQueryField
limitinteger

The top groups kept, within each group of the field before this one.

sortobject

Fields

bystring

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

atrequiredstring (date-time)

The start of the point's interval. The first and last points cover only the part inside the period.

valuesrequiredQueryValues

QueryResult

objectrequired"query_result"
fromrequiredstring (date-time)
torequiredstring (date-time)
intervalrequired"hour" | "day" | "week" | "month" | null
complete_beforerequiredstring (date-time)

Every request that ended before this time is in the answer, as it ended.

groupsrequiredobject[]

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.

Each item

byrequiredmap<string, QueryValue>

Each group-by field and this group's value of it.

valuesrequiredQueryValues
seriesrequiredQueryPoint[]

Every point of the period, in order; empty without an interval.

totalrequiredobject

Every request that matched the filter, in no group.

Fields

valuesrequiredQueryValues
seriesrequiredQueryPoint[]
scanned_bytesrequiredinteger

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.

QueryFields

objectrequired"query_fields"
fieldsrequiredobject[]

Each item

namerequiredQueryField
kindrequired"dimension" | "measure"
typerequired"string" | "enum" | "id" | "integer" | "boolean" | "money"
severalrequiredboolean

True when a request can hold more than one value, as guardrail can.

valuesstring[]

An enum's values.

tag_keysrequiredstring[]

The keys that the environment's requests carried in the last 30 days, sorted.

SignalState

"open" | "dismissed" | "actioned"

Signal

objectrequired"signal"
idrequiredSignalId
kindrequiredstring

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.

organizationrequiredRef | null

The organization its evidence named; null when it named none, or several.

userrequiredRef | null
scorerequirednumber
windowrequiredobject

Fields

fromrequiredTimestamp
torequiredTimestamp
evidencerequiredobject

Fields

requestsrequiredRequestId[]
featuresrequiredmap<string, number>
staterequiredSignalState
created_atrequiredTimestamp
updated_atrequiredTimestamp

EventType

"organization.created" | "organization.updated" | "organization.deleted" | "user.created" | "user.updated" | "system_prompt.created" | "system_prompt.deleted" | "user.suspended" | "user.unsuspended" | "organization.suspended" | "organization.unsuspended" | "signal.detected" | "policy.created" | "policy.updated" | "policy.deleted" | "connection.created" | "connection.updated" | "connection.deleted" | "api_key.created" | "api_key.updated" | "api_key.revoked" | "content_store.updated" | "content_store.deleted" | "webhook_endpoint.created" | "webhook_endpoint.updated" | "webhook_endpoint.deleted" | "webhook_endpoint.disabled" | "webhook_endpoint.test" | "request.blocked" | "request.cut" | "request.content_read" | "limit.threshold_crossed" | "replay.completed" | "replay.failed" | "evidence_pack.completed" | "evidence_pack.failed" | "assessment.completed" | "assessment.failed" | "alert.raised" | "alert.cleared"

Event

objectrequired"event"
idrequiredEventId
eventrequiredEventType
datarequiredobject

The object the event is about, as it was then.

actorrequiredActor | null

Who caused it, or null when traffic did.

environment_idrequiredEnvironmentId
created_atrequiredTimestamp

LimitReached

kindrequired"requests" | "tokens" | "spend"
perrequiredLimitScope
periodrequired"minute" | "day" | "week" | "month"
amountrequiredstring

As a decimal string for every kind, as are used and requested.

usedrequiredstring
requestedrequiredstring
resets_atrequiredTimestamp
tagsLimitTags

Alert

A connection's alert. It is raised once and cleared once, and both events carry the same id.

objectrequired"alert"
idrequiredstring
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.

connection_idrequiredConnectionId
minutesrequiredinteger | null

For throttled, the minutes the settings named; null otherwise.

raised_atrequiredstring (date-time)

The start of the minute whose requests raised it.

cleared_atrequiredstring (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.

"throttled" | "fell_back" | "no_fallback_left" | "limit_threshold"

AlertSettings

objectrequired"alert_settings"
onrequiredAlertKind[]

The alerts raised. Until they are set, every one but no_fallback_left is.

throttled_minutesrequiredinteger

The minutes in a row a connection is throttled before its alert; 5 until set.

AlertSettingsUpdate

onAlertKind[]
throttled_minutesinteger

LimitThreshold

objectrequired"limit_threshold"
limitrequiredobject

Fields

kindrequired"requests" | "tokens" | "spend"
perrequiredLimitScope
periodrequired"minute" | "day" | "week" | "month"
amountrequiredstring

As a decimal string for every kind.

actionrequiredLimitAction
tagsLimitTags
organizationrequiredRef | null
userrequiredRef | null
thresholdrequired80 | 95 | 100

The percentage crossed; 100 when a block limit starts refusing, or when use passes a warn limit.

usedrequiredstring
requestedrequiredstring | null

At 100, what the refused request would have used at most, as its refusal's limit says; null below 100.

resets_atrequiredTimestamp

WebhookEndpointState

"enabled" | "disabled"

WebhookEndpoint

objectrequired"webhook_endpoint"
idrequiredWebhookEndpointId
urlrequiredstring (uri)
eventsrequiredEventType[]

The events it receives; empty for all of them.

staterequiredWebhookEndpointState
disabled_reasonrequired"deliveries_failing" | "disabled_by_team" | null
created_atrequiredTimestamp
updated_atrequiredTimestamp

WebhookEndpointCreate

urlrequiredstring (uri)

A public host: localhost, private addresses and names such as *.internal are refused not_public.

eventsEventType[]

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.

DeliveryState

"pending" | "succeeded" | "failed"

Delivery

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.

objectrequired"delivery"
idrequiredDeliveryId
webhook_endpoint_idrequiredWebhookEndpointId
event_idrequiredEventId
eventrequiredEventType
staterequiredDeliveryState
attemptsrequiredobject[]

Each item

atrequiredTimestamp
statusrequiredinteger | null
duration_msrequirednumber
errorrequiredstring | null

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.

next_attempt_atrequiredstring (date-time) | null
created_atrequiredTimestamp

JobState

"queued" | "running" | "completed" | "failed"

Replay

objectrequired"replay"
idrequiredReplayId
staterequiredJobState
policyrequiredobject

The draft that was replayed.

Fields

policy_idPolicyId | null
matchrequiredMatch
settingsrequiredSettings
fromrequiredTimestamp
torequiredTimestamp
progressrequirednumber
resultrequiredobject | null

What would have changed. Null until completed.

errorrequiredstring | null
created_byrequiredActor
created_atrequiredTimestamp
completed_atrequiredstring (date-time) | null

EffectivePolicyPreview

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.

policy_idPolicyId
matchMatch
settingsSettings
identitiesrequiredobject[]

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.

Each item

organizationExternalId
userExternalId
planExternalId
tagsmap<string, ExternalId>

ReplayCreate

A new draft (match and settings), or changes to an existing policy (policy_id with either). A draft that a save refuses is refused.

policy_idPolicyId
matchMatch
settingsSettings
fromrequiredTimestamp
torequiredTimestamp

EvidencePack

objectrequired"evidence_pack"
idrequiredEvidencePackId
staterequiredJobState
organization_idrequiredOrganizationId
fromrequiredTimestamp
torequiredTimestamp
errorrequiredstring | null
created_byrequiredActor
created_atrequiredTimestamp
completed_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time) | null

When the files are deleted, per the organization's retention.

EvidencePackCreate

organization_idrequiredOrganizationId
fromrequiredTimestamp
torequiredTimestamp

The period's end. One after the pack is generated ends it at generated_at.

Assessment

objectrequired"assessment"
idrequiredAssessmentId
namerequiredstring
staterequired"awaiting_upload" | "queued" | "running" | "completed" | "failed"
formatrequiredAssessmentFormat
uploadrequiredobject | null

Where to upload the logs, while the assessment awaits them.

progressrequiredobject | 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.

errorrequiredstring | null
created_byrequiredActor
created_atrequiredTimestamp
completed_atrequiredstring (date-time) | null

AssessmentFormat

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.

"openai_chat_jsonl" | "openai_responses_jsonl" | "anthropic_messages_jsonl" | "gemini_generate_content_jsonl" | "bedrock_invocation_logs_jsonl" | "metadata_jsonl" | "metadata_csv"

AssessmentReport

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.

objectrequired"assessment_report"
assessment_idrequiredAssessmentId
namerequiredstring
formatrequiredAssessmentFormat
fromrequiredstring (date-time) | null

The earliest accepted row's time, or null when no row was accepted.

torequiredstring (date-time) | null

The latest accepted row's time, or null when no row was accepted.

generated_atrequiredTimestamp
rowsrequiredobject

Fields

readrequiredinteger

Lines that weren't blank.

acceptedrequiredinteger
unreadinteger

Accepted rows whose text the log left out; absent from older reports.

rejectedrequiredmap<string, integer>

Rows rejected, by why.

users_analyzedrequiredinteger
suspicious_usersrequiredinteger
tokensrequiredobject

Fields

totalrequiredinteger
suspiciousrequiredinteger
suspicious_token_sharerequirednumber
estimated_costrequiredobject

In US dollars, at list prices.

Fields

totalrequiredDecimal
suspiciousrequiredDecimal
usersrequiredobject[]

The most suspicious users, most suspicious first.

Each item

userrequiredstring

The user's id as the upload names it.

organizationrequiredstring | null
planrequiredstring | null
scorerequirednumber
requestsrequiredinteger
tokensrequiredinteger
estimated_costrequiredDecimal
signalsrequiredobject[]

Each item

kindrequiredstring

As a signal's kind, such as shared_template.

scorerequirednumber
linesrequiredinteger[]

Lines of the upload behind the signal.

unavailable_signalsrequiredstring[]

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_signalsstring[]

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.

Role

"admin" | "developer" | "viewer"

TeamUpdate

namestring

Member

objectrequired"member"
idrequiredMemberId
emailrequiredstring (email)
namerequiredstring | null
rolerequiredRole
staterequired"invited" | "active"
created_atrequiredTimestamp
updated_atrequiredTimestamp

MemberUpdate

rolerequiredRole

InvitationCreate

emailrequiredstring (email)
rolerequiredRole

TeamEvent

objectrequired"team_event"
idrequiredEventId

Pages this list only; no environment's event has it.

eventrequired"member.invited" | "member.updated" | "member.removed"

member.updated is a change of role.

datarequiredMember

The member as the change left them, or as they were when removed.

actorrequiredActor
created_atrequiredTimestamp

ProjectCreate

namerequiredstring

ProjectUpdate

namestring

Environment

objectrequired"environment"
idrequiredEnvironmentId
project_idrequiredProjectId
namerequiredstring
regionrequiredRegion
productionrequiredboolean

Production environments' keys say live; the rest say test.

api_base_urlrequiredstring
gateway_base_urlrequiredstring
created_atrequiredTimestamp
updated_atrequiredTimestamp

EnvironmentCreate

project_idrequiredProjectId
namerequiredstring
regionrequiredRegion
productionrequiredboolean

EnvironmentUpdate

namestring

FeedbackCreate

A message, a recording, or both. Feedback with neither is refused with an error on message.

pagerequiredstring (uri)

The dashboard page the feedback is about.

messagestring
screenshotobject

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"
bytesrequiredinteger
recordingobject

What the member said instead of, or as well as, a message.

Fields

content_typerequired"audio/webm" | "audio/mp4" | "audio/ogg"
bytesrequiredinteger

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

pagerequiredstring

The page's route, with its parameters named, such as /:environmentId/requests/:id. It has no digits or underscores, which every id has.

callstring

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.

statusinteger

The unreadable answer's status.

namestring

For render, the error's name, such as TypeError.

buildrequiredstring

The dashboard's build, as the name of its script.

Example

{
  "page": "/:environmentId/requests/:id",
  "call": "GET /requests/{id}/content",
  "kind": "unreadable",
  "status": 200,
  "build": "index-C3kZ0d1q.js"
}

Feedback

objectrequired"feedback"
idrequiredFeedbackId
created_atrequiredTimestamp
uploadsrequiredobject

Where to send each file the feedback named, or null for one it didn't.

Fields

screenshotrequiredFeedbackUpload | null
recordingrequiredFeedbackUpload | null

FeedbackUpload

urlrequiredstring (uri)
methodrequired"PUT"
content_typerequiredstring

The Content-Type the PUT must send.

bytesrequiredinteger

The size the PUT must send, which its Content-Length says.

expires_atrequiredTimestamp