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 the team's scripts. The gateway, which the team's servers call, is specified in gateway.md.

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.

Permission	Allows
`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 three and manages the team; developer has all three; viewer has read. A key never holds more than whoever made it. 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"}}.
POST 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.
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 the team's 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 the team enables 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.

`4XX`	`Error` An error. `400 invalid_request`: the body can't be parsed. `401 unauthenticated`. `403 permission_denied` or `wrong_region`. `404 not_found`. `409 conflict`: the object's state doesn't allow the change. `405 method_not_allowed`, with `Allow`. `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.
`5XX`	`Error` `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`: something failed that retrying won't fix, such as a stored object that can't be read; it is logged.

4XX

Error

An error. 400 invalid_request: the body can't be parsed. 401 unauthenticated. 403 permission_denied or wrong_region. 404 not_found. 409 conflict: the object's state doesn't allow the change. 405 method_not_allowed, with Allow. 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.

5XX

Error

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: something failed that retrying won't fix, such as a stored object that can't be read; it is logged.

Organizations

The team's customers, as requests name them.

GET`/organizations`

List organizationsPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`suspended`query	`boolean`

Responses

`200`	`OrganizationList` A page of organizations, newest first by default.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "organization",
      "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "external_id": "acme",
      "name": "Acme",
      "metadata": {"tier": "enterprise"},
      "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

OrganizationCreate

Responses

`201`	`Organization` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"}
}

Example response · 201

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`OrganizationId`

Responses

`200`	`Organization` The organization.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`OrganizationId`

Body

OrganizationUpdate

Responses

`200`	`Organization` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"name": "Acme", "metadata": {"tier": "enterprise"}}

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`OrganizationId`

Responses

`202`	`Organization` The organization, in the `deleting` state.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 202

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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/external_id/{external_id}`

Get an organization by the team's identifierPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`external_id`path, required	`ExternalId`

Responses

`200`	`Organization` The organization.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "organization",
  "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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 the team's product that requests are made for.

GET`/users`

List usersPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId`
`suspended`query	`boolean`

Responses

`200`	`UserList` A page of users.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "external_id": "acme",
      "name": "Acme",
      "metadata": {"tier": "enterprise"},
      "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

UserCreate

Responses

`201`	`User` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"}
}

Example response · 201

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`UserId`

Responses

`200`	`User` The user.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`UserId`

Body

UserUpdate

Responses

`200`	`User` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"name": "Acme", "metadata": {"tier": "enterprise"}}

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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 the team's identifierPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`external_id`path, required	`ExternalId`

Responses

`200`	`User` The user.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "user",
  "id": "user_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "external_id": "acme",
  "name": "Acme",
  "metadata": {"tier": "enterprise"},
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`user_id`query, required	`UserId`
`limit`query	`integer`

Responses

`200`	`RelatedUserList` Related users.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId`
`user_id`query	`UserId`

Responses

`200`	`OrganizationMembershipList` A page of memberships.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId`
`user_id`query	`UserId`
`active`query	`boolean` Only suspensions in force, or only lifted and expired ones.

Responses

`200`	`SuspensionList` A page of suspensions.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "suspension",
      "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "organization": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "user": {
        "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "external_id": "acme"
      },
      "reason": "Set by our scripts.",
      "note": "Set by our scripts.",
      "created_by": {
        "type": "member",
        "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"
      },
      "created_at": "2026-09-29T14:02:11.482Z",
      "expires_at": null,
      "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

SuspensionCreate

Responses

`201`	`Suspension` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "reason": "Set by our scripts.",
  "note": "Set by our scripts.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": null,
  "lifted_at": null,
  "lifted_by": null
}

GET`/suspensions/{id}`

Get a suspensionPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`SuspensionId`

Responses

`200`	`Suspension` The suspension.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "suspension",
  "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "organization": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "reason": "Set by our scripts.",
  "note": "Set by our scripts.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": null,
  "lifted_at": null,
  "lifted_by": null
}

POST`/suspensions/{id}/lift`

Lift a suspensionPermission: manage

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.
`id`path, required	`SuspensionId`

Responses

`200`	`Suspension` The lifted suspension.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "suspension",
  "id": "suspension_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "organization": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "user": {
    "id": "org_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "external_id": "acme"
  },
  "reason": "Set by our scripts.",
  "note": "Set by our scripts.",
  "created_by": {"type": "member", "id": "member_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"},
  "created_at": "2026-09-29T14:02:11.482Z",
  "expires_at": null,
  "lifted_at": null,
  "lifted_by": null
}

Policies

Matches and settings, and how they combine.

GET`/policies`

List policiesPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`

Responses

`200`	`PolicyList` A page of policies.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "policy",
      "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "name": "Free plan",
      "description": "Tighter limits and EU-only routing for the free plan.",
      "match": {"plan": "free"},
      "settings": {
        "routing": {"regions": ["eu"]},
        "limits": {
          "requests": [{"per": "user", "period": "minute", "amount": 20}],
          "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
        },
        "guardrails": {
          "secrets": {"action": "redact", "mode": "enforce"},
          "personal_data": {"action": "pseudonymize", "mode": "enforce"}
        }
      },
      "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

PolicyCreate

Responses

`201`	`Policy` Created, at version 1.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  }
}

Example response · 201

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  },
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`PolicyId`

Responses

`200`	`Policy` The policy, at its current version.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  },
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`PolicyId`

Body

PolicyUpdate

Responses

`200`	`Policy` The policy, at its new version.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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 EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  },
  "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

Its versions are kept, so requests that matched it still explain themselves.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`PolicyId`

Responses

`200`	`Policy` The deleted policy.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  },
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`PolicyId`
`limit`query	`integer`
`order`query	`"asc" \| "desc"`
`before`query	`integer` A version number.
`after`query	`integer` A version number.

Responses

`200`	`PolicyVersionList` A page of versions, newest first by default.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "policy_version",
      "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "version": 1,
      "name": "Acme",
      "match": {"organization": "globex"},
      "settings": {
        "routing": {
          "connections": ["own", "environment"],
          "regions": ["eu", "global"],
          "models": ["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"
            }
          ]
        },
        "guardrails": {
          "secrets": {"action": "redact", "mode": "enforce"},
          "personal_data": {
            "action": "pseudonymize",
            "mode": "enforce",
            "parts": ["user", "tool_result"],
            "kinds": ["email", "phone"],
            "exclusions": ["support@acme.example"]
          },
          "prompt_injection": {
            "action": "cut",
            "mode": "enforce",
            "parts": ["tool_result"]
          },
          "illegal_content": {"action": "block", "mode": "monitor"}
        },
        "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.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`organization`query	`ExternalId`
`user`query	`ExternalId`
`plan`query	`ExternalId`

Responses

`200`	`EffectivePolicy` The combined settings, with the policy behind each.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "effective_policy",
  "identity": {"organization": "acme", "user": "user_42", "plan": "pro"},
  "policies": [{"id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T", "version": 1}],
  "settings": {
    "routing": {
      "connections": ["own", "environment"],
      "regions": ["eu", "global"],
      "models": ["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"
        }
      ]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {
        "action": "pseudonymize",
        "mode": "enforce",
        "parts": ["user", "tool_result"],
        "kinds": ["email", "phone"],
        "exclusions": ["support@acme.example"]
      },
      "prompt_injection": {
        "action": "cut",
        "mode": "enforce",
        "parts": ["tool_result"]
      },
      "illegal_content": {"action": "block", "mode": "monitor"}
    },
    "uninspected": "allow",
    "abuse": {"suspend_at": 0.9}
  },
  "sources": {"routing.regions": ["policy_01M3PQG7FEV8Q4X0M5R7T9W2YA"]}
}

Connections

Ways to reach a model provider.

GET`/connections`

List connectionsPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId` Only the connections this organization owns.
`provider`query	`Provider`
`state`query	`ConnectionState`

Responses

`200`	`ConnectionList` A page of connections.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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,
      "region": "eu",
      "models": ["gpt-5", "gpt-5-mini"],
      "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

ConnectionCreate

Responses

`201`	`Connection` Created, as a draft.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ConnectionId`

Responses

`200`	`Connection` The connection. Its credential is never returned.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ConnectionId`

Body

ConnectionUpdate

Responses

`200`	`Connection` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "name": "Acme",
  "models": ["models"],
  "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,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ConnectionId`

Responses

`200`	`Connection` The deleted connection.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "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 and checks the answers, without changing the connection's state.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ConnectionId`
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Responses

`200`	`ConnectionTest` The test's checks.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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 the team's own AWS account.

GET`/content_store`

Get the content storePermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.

Responses

`200`	`ContentStore` The content store.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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 (R20), such as eu-central-1 for an eu environment; any other is refused with 422 validation_failed, code outside_region.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

ContentStoreSet

Responses

`200`	`ContentStore` Set.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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, the team's to keep or delete; Alectura reads none of it any more.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Responses

`200`	`ContentStore` Removed, as it was.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Responses

`200`	`ContentStoreTest` The test's result, and the store after it.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`type`query	`ApiKeyType`
`state`query	`ApiKeyState`

Responses

`200`	`ApiKeyList` A page of keys, without their secrets.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

ApiKeyCreate

Responses

`201`	`ApiKeyWithSecret` Created, with its secret.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "name": "Acme",
  "type": "sending",
  "permissions": ["read"],
  "expires_at": "2026-09-29T14:02:11.482Z"
}

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ApiKeyId`

Responses

`200`	`ApiKey` The key, without its secret.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ApiKeyId`

Body

ApiKeyUpdate

Responses

`200`	`ApiKey` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"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 the key within 10 seconds. A revoked key can't be restored.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ApiKeyId`

Responses

`200`	`ApiKey` The revoked key.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.
`id`path, required	`ApiKeyId`

Body

`grace_period_seconds`	`integer`

Responses

`200`	`ApiKeyWithSecret` The key, with its new secret.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId`
`user_id`query	`UserId`
`conversation_id`query	`ConversationId`
`verdict`query	`Verdict`
`model`query	`string`
`connection_id`query	`ConnectionId`
`policy_id`query	`PolicyId`
`guardrail`query	`Guardrail` Only requests with a finding from this guardrail.
`created_after`query	`string (date-time)`
`created_before`query	`string (date-time)`

Responses

`200`	`RequestList` A page of requests.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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",
      "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "endpoint": "openai.chat_completions",
      "model": "claude-sonnet-5-5",
      "stream": false,
      "status": 1,
      "verdict": "passed",
      "refusal": {"code": "user_suspended"},
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "attempts": [
        {
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "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": "record",
          "mode": "monitor",
          "applied": false,
          "block": 1,
          "part": "system"
        }
      ],
      "coverage": [
        {
          "block": 1,
          "part": "system",
          "modality": "text",
          "inspected_by": ["secrets"],
          "reason": "images_uninspected"
        }
      ],
      "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
      },
      "content": {
        "retained": false,
        "retention": "none",
        "expires_at": null,
        "reason": "Set by our scripts."
      }
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

GET`/requests/{id}`

Get a requestPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`RequestId`

Responses

`200`	`Request` The request's record. Its content is fetched separately.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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",
  "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "endpoint": "openai.chat_completions",
  "model": "claude-sonnet-5-5",
  "stream": false,
  "status": 1,
  "verdict": "passed",
  "refusal": {"code": "user_suspended"},
  "connection": {
    "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "provider": "openai",
    "region": "us"
  },
  "attempts": [
    {
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "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": "record",
      "mode": "monitor",
      "applied": false,
      "block": 1,
      "part": "system"
    }
  ],
  "coverage": [
    {
      "block": 1,
      "part": "system",
      "modality": "text",
      "inspected_by": ["secrets"],
      "reason": "images_uninspected"
    }
  ],
  "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},
  "content": {
    "retained": false,
    "retention": "none",
    "expires_at": null,
    "reason": "Set by our scripts."
  }
}

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 keyed 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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`RequestId`
`version`query, required	`ContentVersion`
`view`query	`"raw" \| "events" \| "assembled"` For a streamed response: `raw` is the stream as it arrived; `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

`200`	`object` The content.
`410`	`Error` The content has passed its retention, or was never kept.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

Get an attachmentPermission: read_content

Recorded as a request.content_read event.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`RequestId`
`hash`path, required	`string`

Responses

`200`	`string` The attachment's bytes, with its media type.
`410`	`Error` The attachment has passed its retention, or was never kept.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

GET`/requests/{id}/conversation`

The requests in this request's conversationPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`RequestId`
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.

Responses

`200`	`RequestList` The conversation's requests, oldest first.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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",
      "api_key_id": "key_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
      "endpoint": "openai.chat_completions",
      "model": "claude-sonnet-5-5",
      "stream": false,
      "status": 1,
      "verdict": "passed",
      "refusal": {"code": "user_suspended"},
      "connection": {
        "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
        "provider": "openai",
        "region": "us"
      },
      "attempts": [
        {
          "connection": {
            "id": "conn_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
            "provider": "openai",
            "region": "us"
          },
          "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": "record",
          "mode": "monitor",
          "applied": false,
          "block": 1,
          "part": "system"
        }
      ],
      "coverage": [
        {
          "block": 1,
          "part": "system",
          "modality": "text",
          "inspected_by": ["secrets"],
          "reason": "images_uninspected"
        }
      ],
      "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
      },
      "content": {
        "retained": false,
        "retention": "none",
        "expires_at": null,
        "reason": "Set by our scripts."
      }
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

Findings

Detector matches, and the team's labels on them.

GET`/findings/summary`

Findings by guardrail and kind, with samplesPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`from`query, required	`string (date-time)`
`to`query, required	`string (date-time)`
`guardrail`query	`Guardrail`
`organization_id`query	`OrganizationId`

Responses

`200`	`FindingsSummary` Counts, minutes behind.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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": "action",
      "mode": "monitor",
      "count": 1,
      "requests": 1,
      "samples": ["req_01J9ZQ6V8D3K4M5N6P7Q8R9S0T"]
    }
  ]
}

GET`/findings/{id}/dispositions`

List a finding's dispositionsPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`FindingId`

Responses

`200`	`DispositionList` The finding's dispositions, newest first.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`FindingId`
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

DispositionCreate

Responses

`201`	`Disposition` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"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, 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.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`from`query, required	`string (date-time)`
`to`query, required	`string (date-time)`
`interval`query	`"hour" \| "day"` The width of each point in the series.
`organization_id`query	`OrganizationId`
`user_id`query	`UserId`

Responses

`200`	`Summary` Totals, minutes behind.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "summary",
  "from": "2026-09-29T14:02:11.482Z",
  "to": "2026-09-29T14:02:11.482Z",
  "interval": "hour",
  "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
    },
    "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
        },
        "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`from`query, required	`string (date-time)`
`to`query, required	`string (date-time)`
`user_ids`query, required	`UserId[]` Up to 100 users.

Responses

`200`	`SummaryList` A summary for each user, minutes behind.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "list",
  "data": [
    {
      "object": "summary",
      "from": "2026-09-29T14:02:11.482Z",
      "to": "2026-09-29T14:02:11.482Z",
      "interval": "hour",
      "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
        },
        "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
            },
            "organizations": 1,
            "users": 1,
            "models": {"key": 1},
            "providers": {"key": 1}
          }
        }
      ]
    }
  ],
  "list_metadata": {"before": null, "after": null}
}

Signals

Observations about users and organizations drawn from many requests.

GET`/signals`

List signalsPermission: read

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`organization_id`query	`OrganizationId`
`user_id`query	`UserId`
`state`query	`SignalState`

Responses

`200`	`SignalList` A page of signals.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`SignalId`

Responses

`200`	`Signal` The signal.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.
`id`path, required	`SignalId`

Responses

`200`	`Signal` The dismissed signal.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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 the team's 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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`

Responses

`200`	`SystemPromptList` A page of declared system prompts.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

SystemPromptCreate

Responses

`201`	`SystemPrompt` Declared.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`SystemPromptId`

Responses

`200`	`SystemPrompt` The declaration.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`SystemPromptId`

Responses

`200`	`SystemPrompt` The declaration, as it was.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`events`query	`EventType[]` Only these event types.
`created_after`query	`string (date-time)`
`created_before`query	`string (date-time)`

Responses

`200`	`EventList` A page of events.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`EventId`

Responses

`200`	`Event` The event.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`

Responses

`200`	`WebhookEndpointList` A page of endpoints.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

WebhookEndpointCreate

Responses

`201`	`WebhookEndpointWithSecret` Created, with its signing secret.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`WebhookEndpointId`

Responses

`200`	`WebhookEndpoint` The endpoint.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`WebhookEndpointId`

Body

WebhookEndpointUpdate

Responses

`200`	`WebhookEndpoint` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`WebhookEndpointId`

Responses

`200`	`WebhookEndpoint` The deleted endpoint.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.
`id`path, required	`WebhookEndpointId`

Responses

`200`	`WebhookEndpointWithSecret` The endpoint, with its new signing secret.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`WebhookEndpointId`
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Responses

`200`	`Delivery` The test delivery.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`WebhookEndpointId`
`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`state`query	`DeliveryState`

Responses

`200`	`DeliveryList` A page of deliveries.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.
`id`path, required	`DeliveryId`

Responses

`200`	`Delivery` The delivery, with the new attempt.
`410`	`Error` The delivery's event has passed its retention.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

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 settings only.

Parameters

`Alectura-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

ReplayCreate

Responses

`202`	`Replay` Queued.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "match": {"organization": "globex"},
  "settings": {
    "routing": {
      "connections": ["own", "environment"],
      "regions": ["eu", "global"],
      "models": ["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"
        }
      ]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {
        "action": "pseudonymize",
        "mode": "enforce",
        "parts": ["user", "tool_result"],
        "kinds": ["email", "phone"],
        "exclusions": ["support@acme.example"]
      },
      "prompt_injection": {
        "action": "cut",
        "mode": "enforce",
        "parts": ["tool_result"]
      },
      "illegal_content": {"action": "block", "mode": "monitor"}
    },
    "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": {
        "connections": ["own", "environment"],
        "regions": ["eu", "global"],
        "models": ["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"
          }
        ]
      },
      "guardrails": {
        "secrets": {"action": "redact", "mode": "enforce"},
        "personal_data": {
          "action": "pseudonymize",
          "mode": "enforce",
          "parts": ["user", "tool_result"],
          "kinds": ["email", "phone"],
          "exclusions": ["support@acme.example"]
        },
        "prompt_injection": {
          "action": "cut",
          "mode": "enforce",
          "parts": ["tool_result"]
        },
        "illegal_content": {"action": "block", "mode": "monitor"}
      },
      "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,
    "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`ReplayId`

Responses

`200`	`Replay` The replay, with its result once completed.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example response · 200

{
  "object": "replay",
  "id": "replay_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "state": "queued",
  "policy": {
    "policy_id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
    "match": {"organization": "globex"},
    "settings": {
      "routing": {
        "connections": ["own", "environment"],
        "regions": ["eu", "global"],
        "models": ["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"
          }
        ]
      },
      "guardrails": {
        "secrets": {"action": "redact", "mode": "enforce"},
        "personal_data": {
          "action": "pseudonymize",
          "mode": "enforce",
          "parts": ["user", "tool_result"],
          "kinds": ["email", "phone"],
          "exclusions": ["support@acme.example"]
        },
        "prompt_injection": {
          "action": "cut",
          "mode": "enforce",
          "parts": ["tool_result"]
        },
        "illegal_content": {"action": "block", "mode": "monitor"}
      },
      "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,
    "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

EvidencePackCreate

Responses

`202`	`EvidencePack` Queued.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{
  "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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`EvidencePackId`

Responses

`200`	`EvidencePack` The evidence pack.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`EvidencePackId`
`format`query	`"pdf" \| "json"`

Responses

`200`	`string` The pack.
`410`	`Error` The pack's files have been deleted.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

AssessmentCreate

Responses

`201`	`Assessment` Created, waiting for its upload.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`AssessmentId`

Responses

`200`	`Assessment` The assessment.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Environment`header	`EnvironmentId` The environment a session acts on. Required with a session; with a management key, it may be sent only if it names the key's own environment.
`id`path, required	`AssessmentId`
`format`query	`"pdf" \| "json"`

Responses

`200`	`string` The report.
`410`	`Error` The assessment's files have been deleted.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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, "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"]
}

Team

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

GET`/team`

Get the signed-in member's team

Responses

`200`	`Team` The team.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

`200`	`Team` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`

Responses

`200`	`MemberList` A page of members, invited ones included.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

`id`path, required	`MemberId`

Body

MemberUpdate

Responses

`200`	`Member` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

`id`path, required	`MemberId`

Responses

`200`	`Member` The removed member.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

InvitationCreate

Responses

`201`	`Member` The invited member.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"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`/projects`

List projects

Parameters

`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`

Responses

`200`	`ProjectList` A page of projects.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

ProjectCreate

Responses

`201`	`Project` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

`id`path, required	`ProjectId`

Responses

`200`	`Project` The project.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

`id`path, required	`ProjectId`

Body

ProjectUpdate

Responses

`200`	`Project` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

{"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 the team's environments, in every region

Parameters

`limit`query	`integer`
`before`query	`string` An object id. Returns the page before it.
`after`query	`string` An object id. Returns the page after it.
`order`query	`"asc" \| "desc"`
`project_id`query	`ProjectId`

Responses

`200`	`EnvironmentList` A page of environments.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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 only its own region.

Parameters

`Idempotency-Key`header	`string` Makes a retry return the first result for 24 hours. The same key with a different body is refused with `422 idempotency_key_reused`.

Body

EnvironmentCreate

Responses

`201`	`Environment` Created.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

`id`path, required	`EnvironmentId`

Responses

`200`	`Environment` The environment.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

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

`id`path, required	`EnvironmentId`

Body

EnvironmentUpdate

Responses

`200`	`Environment` Updated.
`4XX`	An error: see Errors
`5XX`	A service is unavailable: see Errors

Example request body

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

Webhook events

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

`organization.created`	`Event & object` An organization was created, by the API or by the first request that named it.
`organization.updated`	`Event & object` An organization's name or metadata changed.
`organization.deleted`	`Event & object` An organization was deleted. Its key is already destroyed.
`user.created`	`Event & object` A user was created, by the API or by the first request that named it.
`user.updated`	`Event & object` A user's name or metadata changed.
`system_prompt.created`	`Event & object` A system prompt was declared as the app's own.
`system_prompt.deleted`	`Event & object` A declared system prompt was withdrawn.
`user.suspended`	`Event & object` A user was suspended, by a team member, a key or a policy.
`user.unsuspended`	`Event & object` A user's suspension was lifted or expired.
`organization.suspended`	`Event & object` An organization was suspended, by a team member, a key or a policy.
`organization.unsuspended`	`Event & object` An organization's suspension was lifted or expired.
`signal.detected`	`Event & object` A signal job observed something about a user or organization.
`policy.created`	`Event & object` A policy was created.
`policy.updated`	`Event & object` A policy changed, making a new version.
`policy.deleted`	`Event & object` A policy was deleted.
`connection.created`	`Event & object` A connection was created, as a draft.
`connection.updated`	`Event & object` A connection changed, including its state.
`connection.deleted`	`Event & object` A connection was deleted.
`api_key.created`	`Event & object` An API key was created. The event never carries the secret.
`api_key.updated`	`Event & object` An API key was renamed, disabled, enabled, rotated or given an expiry.
`api_key.revoked`	`Event & object` An API key was revoked.
`webhook_endpoint.disabled`	`Event & object` An endpoint was disabled because a delivery to it failed five times. It goes to the other endpoints.
`webhook_endpoint.test`	`Event & object` A test delivery, sent only to the endpoint being tested.
`request.blocked`	`Event & object` A policy refused a request. Suspensions count.
`request.cut`	`Event & object` A guardrail cut a response.
`request.content_read`	`Event & object` Someone read a request's content or an attachment.
`limit.threshold_crossed`	`Event & object` A limit passed 80% or 95% of its amount, or started refusing.
`replay.completed`	`Event & object` A replay finished.
`replay.failed`	`Event & object` A replay failed.
`evidence_pack.completed`	`Event & object` An evidence pack is ready to download.
`evidence_pack.failed`	`Event & object` An evidence pack failed.
`assessment.completed`	`Event & object` An assessment's report is ready.
`assessment.failed`	`Event & object` An assessment failed.

Schemas

`Error`

coderequired string

messagerequired string

errors

object[]

Each item

`field`required	`string` A dotted path into the body, such as `settings.routing.regions`.
`code`required	`string`
`message`	`string`

request_idrequired RequestId

`ListMetadata`

`before`required	`string \| null`
`after`required	`string \| null`

`Timestamp`

string (date-time)

`Money`

`amount`required	`Decimal`
`currency`required	`"USD"`
`estimated`required	`boolean` True for list prices from the pinned price map, rather than a provider's bill.

`Decimal`

string

`ExternalId`

The team's own identifier, as the Alectura-* headers carry it.

string

`Metadata`

map<string, string>

`Actor`

Who made a change.

`type`required	`"api_key" \| "member" \| "policy" \| "system"`
`id`required	`string \| null` The key's, member'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

`EnvironmentId`

string

`Ref`

A reference to an organization or user, with the team's identifier.

`id`required	`string`
`external_id`required	`ExternalId`

Example

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

`Organization`

`object`required	`"organization"`
`id`required	`OrganizationId`
`external_id`required	`ExternalId`
`name`required	`string \| null`
`metadata`required	`Metadata`
`plan`required	`string \| null` The plan named by its latest request that sent `Alectura-Plan`; null until one does.
`suspended`required	`boolean`
`state`required	`"active" \| "deleting"`
`first_seen_at`required	`string (date-time) \| null`
`last_seen_at`required	`string (date-time) \| null`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`OrganizationCreate`

`external_id`required	`ExternalId`
`name`	`string`
`metadata`	`Metadata`

`OrganizationUpdate`

`name`	`string \| null`
`metadata`	`Metadata`

`OrganizationList`

`object`required	`"list"`
`data`required	`Organization[]`
`list_metadata`required	`ListMetadata`

`User`

`object`required	`"user"`
`id`required	`UserId`
`external_id`required	`ExternalId`
`name`required	`string \| null`
`metadata`required	`Metadata`
`suspended`required	`boolean`
`signals`	`UserSignal[]` 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_at`required	`string (date-time) \| null`
`last_seen_at`required	`string (date-time) \| null`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`UserSignal`

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

`id`required	`SignalId`
`kind`required	`string` What was observed, as the signal's `kind`.
`score`required	`number`

`UserCreate`

`external_id`required	`ExternalId`
`name`	`string`
`metadata`	`Metadata`

`UserUpdate`

`name`	`string \| null`
`metadata`	`Metadata`

`UserList`

`object`required	`"list"`
`data`required	`User[]`
`list_metadata`required	`ListMetadata`

`RelatedUserList`

objectrequired "list"

datarequired

object[]

Each item

`object`required	`"related_user"`
`user`required	`Ref`
`shared_fingerprints`required	`integer` How many prompt templates both users' requests share.

list_metadatarequired ListMetadata

`OrganizationMembership`

`object`required	`"organization_membership"`
`id`required	`OrganizationMembershipId`
`organization`required	`Ref`
`user`required	`Ref`
`first_seen_at`required	`Timestamp`
`last_seen_at`required	`Timestamp`

`OrganizationMembershipList`

`object`required	`"list"`
`data`required	`OrganizationMembership[]`
`list_metadata`required	`ListMetadata`

`Suspension`

`object`required	`"suspension"`
`id`required	`SuspensionId`
`organization`required	`Ref \| null` Set when an organization is suspended.
`user`required	`Ref \| null` Set when a user is suspended.
`reason`required	`string` A short reason, such as `signals` for one a policy made.
`note`required	`string \| null`
`created_by`required	`Actor`
`created_at`required	`Timestamp`
`expires_at`required	`string (date-time) \| null`
`lifted_at`required	`string (date-time) \| null`
`lifted_by`required	`Actor \| null`

`SuspensionCreate`

Names exactly one of organization_id and user_id.

`organization_id`	`OrganizationId`
`user_id`	`UserId`
`reason`required	`string`
`note`	`string`
`expires_at`	`Timestamp`

Example

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

`SuspensionList`

`object`required	`"list"`
`data`required	`Suspension[]`
`list_metadata`required	`ListMetadata`

`SystemPrompt`

A system prompt the team declared as its app's own. Its text isn't kept.

`object`required	`"system_prompt"`
`id`required	`SystemPromptId`
`name`required	`string \| null`
`fingerprint`required	`string` The keyed hash of the prompt's text, as requests' prompts are hashed.
`created_at`required	`Timestamp`

`SystemPromptCreate`

`text`required	`string` The prompt, exactly as the app sends it, several system blocks joined by line breaks. Only its fingerprint is kept.
`name`	`string \| null`

`SystemPromptList`

`object`required	`"list"`
`data`required	`SystemPrompt[]`
`list_metadata`required	`ListMetadata`

`Policy`

`object`required	`"policy"`
`id`required	`PolicyId`
`name`required	`string`
`description`required	`string \| null`
`match`required	`Match`
`settings`required	`Settings`
`version`required	`integer`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

Example

{
  "object": "policy",
  "id": "policy_01J9ZQ6V8D3K4M5N6P7Q8R9S0T",
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  },
  "version": 1,
  "created_at": "2026-09-29T14:02:11.482Z",
  "updated_at": "2026-09-29T14:02:11.482Z"
}

`PolicyCreate`

`name`required	`string`
`description`	`string`
`match`required	`Match`
`settings`required	`Settings`

Example

{
  "name": "Free plan",
  "description": "Tighter limits and EU-only routing for the free plan.",
  "match": {"plan": "free"},
  "settings": {
    "routing": {"regions": ["eu"]},
    "limits": {
      "requests": [{"per": "user", "period": "minute", "amount": 20}],
      "spend": [{"per": "user", "period": "day", "amount": "0.50"}]
    },
    "guardrails": {
      "secrets": {"action": "redact", "mode": "enforce"},
      "personal_data": {"action": "pseudonymize", "mode": "enforce"}
    }
  }
}

`PolicyUpdate`

`name`	`string`
`description`	`string \| null`
`match`	`Match` Replaces the whole match, never merges into it: a field left out no longer selects.
`settings`	`Settings`

Example

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

`PolicyList`

`object`required	`"list"`
`data`required	`Policy[]`
`list_metadata`required	`ListMetadata`

`PolicyVersion`

`object`required	`"policy_version"`
`policy_id`required	`PolicyId`
`version`required	`integer`
`name`required	`string`
`match`required	`Match`
`settings`required	`Settings`
`deleted`required	`boolean` True for the version that deleted the policy.
`created_by`required	`Actor`
`created_at`required	`Timestamp`

`PolicyVersionList`

`object`required	`"list"`
`data`required	`PolicyVersion[]`
`list_metadata`required	`ListMetadata`

`Match`

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

`organization`	`MatchValue`
`user`	`MatchValue`
`plan`	`MatchValue`

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

`Settings`

Each setting combines across matching policies by the rule in its description, and every rule only tightens. A setting no matching policy sets takes its default.

routing RoutingSettings

retention RetentionSettings

limits LimitSettings

guardrails GuardrailSettings

uninspected

"allow" | "block"

What to do with content nothing can inspect, such as images. block wins. Default allow, with the content recorded as uninspected.

abuse

object

What happens when a signal flags a user or organization for abuse.

Fields

`suspend_at`	`number` Suspend the user when a signal's score reaches this; an organization is never suspended automatically. The lowest wins. Default: never.

`RoutingSettings`

connections

("own" | "environment")[]

Whose connections may serve a request, in order. own is the organization's own connections: an organization that owns any is served by them alone, so a request none of them can serve is refused with no_allowed_connection, while one that owns none, or a request without an organization, is served by the environment's. environment is the environment's, so [own, environment] falls back to them. Across policies, the members every policy allows, in the order of the most specific policy that sets it. Default ["own"]. A policy lists at least one; an effective policy's list is empty when its policies allow nothing in common.

regions

ProviderRegion[]

Where a provider may process a request, in order of preference. Across policies, the members every policy allows, in the order of the most specific policy that sets it. Default: the environment's own region. A policy lists at least one; an effective policy's list is empty when its policies allow nothing in common, and then refuses every request.

models

string[]

The models a request may use; an id without a date matches every dated version. Across policies, the intersection. Default: any model an active connection serves.

data_terms

object

The data terms a connection must declare (Connection.data_terms) to serve a request. A connection whose terms are undeclared doesn't meet a requirement. When no connection that meets them serves the model, the request is refused with no_allowed_connection. Default: any terms.

Fields

`retention`	`"any" \| "zero"` `zero`: only connections whose provider keeps nothing it's sent. Across policies, `zero` wins. Content retention `none` doesn't imply it.
`training`	`"any" \| "no"` `no`: only connections whose provider doesn't train on what it's sent. Across policies, `no` wins.

Example

{
  "connections": ["own", "environment"],
  "regions": ["eu", "global"],
  "models": ["claude-sonnet-5-5", "claude-haiku-4-5"],
  "data_terms": {"retention": "zero", "training": "no"}
}

`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 the team rather than by Alectura: in the environment's content store (/content_store), for as long as the team keeps 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 pair of per and period, the lowest amount among matching policies wins; limits for different pairs all apply. requests and tokens take a minute or a day, and spend a day, a week or a month. A limit over a minute refuses with 429; over a day, week or month, with 402. Periods are calendar periods in UTC, and weeks start on Monday.

max_output_tokens

integer

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

requests

object[]

Each item

`per`required	`LimitScope`
`period`required	`"minute" \| "day"`
`amount`required	`integer`

tokens

object[]

Input and output tokens together.

Each item

`per`required	`LimitScope`
`period`required	`"minute" \| "day"`
`amount`required	`integer`

spend

object[]

Estimated cost at list prices, in USD.

Each item

`per`required	`LimitScope`
`period`required	`"day" \| "week" \| "month"`
`amount`required	`Decimal`

Example

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

`LimitScope`

A request without a user or organization isn't counted against limits for it.

"user" | "organization"

`GuardrailSettings`

Across policies: each guardrail's action and mode take the strictest value, in the order listed for each; parts and kinds the union; exclusions the intersection. A guardrail no matching policy sets doesn't run.

secrets

object

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.

Fields

`action`required	`"record" \| "redact" \| "block"`
`mode`required	`GuardrailMode`
`parts`	`Parts`

personal_data

object

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. 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. person_name, street_address and date_of_birth are found in English text without a model (crates/guard/accuracy/README.md has how well).

Fields

`action`required	`"record" \| "pseudonymize" \| "redact" \| "block"`
`mode`required	`GuardrailMode`
`parts`	`Parts`
`kinds`	`("email" \| "phone" \| "card_number" \| "iban" \| "ip_address" \| "national_id" \| "person_name" \| "street_address" \| "date_of_birth")[]` Default all.
`exclusions`	`string[]` Exact values never treated as personal data, such as the team's support address.

prompt_injection

object

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.

Fields

`action`required	`"flag" \| "cut"`
`mode`required	`GuardrailMode`
`parts`	`Parts`

illegal_content

object

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; flag 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 in monitor mode.

Fields

`action`required	`"flag" \| "block"`
`mode`required	`GuardrailMode`
`parts`	`Parts`
`kinds`	`("violent_crimes" \| "non_violent_crimes" \| "sex_crimes" \| "child_sexual_exploitation" \| "weapons")[]` Default all.

Example

{
  "secrets": {"action": "redact", "mode": "enforce"},
  "personal_data": {
    "action": "pseudonymize",
    "mode": "enforce",
    "parts": ["user", "tool_result"],
    "kinds": ["email", "phone"],
    "exclusions": ["support@acme.example"]
  },
  "prompt_injection": {"action": "cut", "mode": "enforce", "parts": ["tool_result"]},
  "illegal_content": {"action": "block", "mode": "monitor"}
}

`GuardrailMode`

monitor records what the guardrail would do; enforce does it. enforce wins.

"monitor" | "enforce"

`Parts`

The parts of a request a guardrail inspects. Default all of them that the guardrail reads. Only secrets and personal_data read output; a policy that names it for another guardrail is refused with 422 validation_failed.

Part[]

`Part`

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

`EffectivePolicy`

objectrequired "effective_policy"

identityrequired

object

Fields

`organization`required	`string \| null`
`user`required	`string \| null`
`plan`required	`string \| null`

policiesrequired

PolicyRef[]

The matching policies, at their current versions.

settingsrequired

Settings

The settings as they apply. One no matching policy sets shows at its default: routing to the environment's region on ["own"] connections, retention none and uninspected: allow; a guardrail or a limit no policy sets is absent, since its default is to do nothing.

sourcesrequired

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

`PolicyRef`

`id`required	`PolicyId`
`version`required	`integer`

`Provider`

gemini is the Gemini API, in its own format. 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" | "gemini" | "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.

`retention`required	`"undeclared" \| "zero" \| "retains"`
`training`required	`"undeclared" \| "no" \| "yes"`

`Credential`

Write-only. Reading a connection returns only CredentialHint.

object | object

`CredentialHint`

`type`required	`"api_key" \| "aws_role"`
`hint`required	`string` The last four characters of a key, or a role's name.

`Owner`

Who owns the connection.

object | object

`Connection`

`object`required	`"connection"`
`id`required	`ConnectionId`
`name`required	`string`
`provider`required	`Provider`
`owner`required	`Owner`
`base_url`required	`"https://api.openai.com/v1" \| "https://eu.api.openai.com/v1" \| "https://api.anthropic.com" \| "https://generativelanguage.googleapis.com" \| null` For OpenAI, Anthropic and Gemini.
`aws_region`required	`string \| null` For Bedrock.
`inference_profile`required	`"us" \| "eu" \| "apac" \| "au" \| "global" \| null` For Bedrock, a cross-region inference profile, or null for the region's own endpoint.
`region`required	`ProviderRegion` Where the endpoint promises to process requests. Derived, never set.
`models`required	`string[]` The models it serves, by the ids clients send.
`data_terms`required	`DataTerms`
`credential`required	`CredentialHint`
`aws_external_id`required	`string \| null` For an `aws_role` credential, the external id the role's trust policy must require.
`state`required	`ConnectionState`
`cooling_down_until`required	`string (date-time) \| null` Set while repeated failures keep the connection out of routing.
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

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,
  "region": "eu",
  "models": ["gpt-5", "gpt-5-mini"],
  "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`

`name`required	`string`
`provider`required	`Provider`
`owner`	`Owner` Default the environment.
`base_url`	`"https://api.openai.com/v1" \| "https://eu.api.openai.com/v1" \| "https://api.anthropic.com" \| "https://generativelanguage.googleapis.com"`
`aws_region`	`string`
`inference_profile`	`"us" \| "eu" \| "apac" \| "au" \| "global" \| null`
`models`required	`string[]`
`data_terms`	`DataTerms`
`credential`	`Credential` 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-…"}
}

`ConnectionUpdate`

`name`	`string`
`models`	`string[]`
`data_terms`	`DataTerms`
`credential`	`Credential`
`state`	`ConnectionState`

`ConnectionList`

`object`required	`"list"`
`data`required	`Connection[]`
`list_metadata`required	`ListMetadata`

`ConnectionTest`

objectrequired "connection_test"

connection_idrequired ConnectionId

passedrequired

boolean

True when every check passed.

checksrequired

object[]

Each item

`name`required	`string` What was checked, such as `credential`, `model:gpt-5`, `stream` or `usage`.
`passed`required	`boolean`
`reason`required	`string \| null` Why it failed, such as `invalid_credential`, `model_unavailable`, `invalid_stream`, `missing_usage` or `region_not_allowed`.
`message`required	`string \| null`
`upstream_status`	`integer \| null` The provider's HTTP status, when it answered.

created_atrequired Timestamp

`ContentStore`

Where team-held content goes: an S3 bucket in the team's 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.

`object`required	`"content_store"`
`bucket`required	`string`
`region`required	`string`
`prefix`required	`string` What every key starts with: empty, or ending in `/`.
`role_arn`required	`string`
`external_id`required	`string` What the role's trust policy must require as `sts:ExternalId`.
`state`required	`"draft" \| "active"` Only an active store takes content. A store becomes active when its test passes.
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`ContentStoreSet`

`bucket`required	`string`
`region`required	`string` The bucket's AWS region, which must be in the environment's region, so content never leaves it.
`prefix`	`string`
`role_arn`required	`string`

`ContentStoreTest`

`object`required	`"content_store_test"`
`passed`required	`boolean`
`message`required	`string \| null` Why it failed, such as the role that couldn't be assumed or the key that couldn't be written.
`content_store`required	`ContentStore`

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

`object`required	`"api_key"`
`id`required	`ApiKeyId`
`name`required	`string`
`type`required	`ApiKeyType`
`permissions`required	`Permission[]` `send` alone for a sending key; any of the others for a management key.
`label`required	`string` The key with all but its prefix and last six characters masked.
`state`required	`ApiKeyState`
`expires_at`required	`string (date-time) \| null`
`previous_secret_expires_at`required	`string (date-time) \| null` After a rotation, when the old secret stops working.
`created_by`required	`Actor`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`ApiKeyWithSecret`

ApiKey & object

`ApiKeyCreate`

`name`required	`string`
`type`	`ApiKeyType` Default `sending`.
`permissions`	`("read" \| "read_content" \| "manage")[]` For a management key; a sending key always has `send` alone.
`expires_at`	`Timestamp`

`ApiKeyUpdate`

`name`	`string`
`state`	`"active" \| "disabled"`
`expires_at`	`string (date-time) \| null`

`ApiKeyList`

`object`required	`"list"`
`data`required	`ApiKey[]`
`list_metadata`required	`ListMetadata`

`Verdict`

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

`Guardrail`

"secrets" | "personal_data" | "prompt_injection" | "illegal_content"

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

`ConnectionRef`

`id`required	`ConnectionId`
`provider`required	`Provider`
`region`required	`ProviderRegion`

`Request`

objectrequired "request"

idrequired RequestId

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_atrequired Timestamp

completed_atrequired string (date-time) | null

organizationrequired Ref | null

userrequired Ref | null

planrequired string | null

conversation_idrequired ConversationId | null

api_key_idrequired ApiKeyId

endpointrequired

"openai.chat_completions" | "openai.responses" | "anthropic.messages" | "gemini.generate_content" | null

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

modelrequired

string | null

The model the request asked for; null for a request refused before its body was read.

streamrequired boolean

statusrequired

integer | null

The HTTP status the client received; null while pending.

verdictrequired Verdict

refusalrequired

object | null

Our refusal or cut, if there was one.

connectionrequired

ConnectionRef | null

The connection that served the request, if any did.

attemptsrequired

object[]

Every connection tried, in order.

Each item

`connection`required	`ConnectionRef`
`started_at`required	`Timestamp`
`status`required	`integer \| null` The provider's HTTP status; null if it never answered.
`error`required	`string \| null` Why the attempt failed, such as `provider_timeout` or the provider's own error code.
`duration_ms`required	`number`

policiesrequired

PolicyRef[]

The policies that matched, at their versions then.

findingsrequired Finding[]

coveragerequired

object[]

For each block, the detectors that ran on it, or why none did. A request that reached a provider ends with 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.

Each item

`block`required	`integer`
`part`required	`Part`
`modality`required	`"text" \| "image" \| "audio" \| "video" \| "file" \| "reasoning"`
`inspected_by`required	`Guardrail[]`
`reason`required	`"images_uninspected" \| "audio_uninspected" \| "video_uninspected" \| "files_uninspected" \| "uninspectable" \| "encrypted" \| "not_selected" \| 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.

usagerequired Usage | null

costrequired Money | null

timingsrequired

object

Fields

`overhead_ms`required	`number` Time the gateway added, excluding the provider.
`first_byte_ms`required	`number \| null`
`duration_ms`required	`number \| null`

contentrequired

object

Fields

`retained`required	`boolean`
`retention`required	`"none" \| "team" \| "7d" \| "30d" \| "90d" \| "365d"`
`expires_at`required	`string (date-time) \| null`
`reason`required	`string \| null` Why content wasn't kept, such as `retention_none`.

`Usage`

`input_tokens`required	`integer` Input tokens not read from or written to the cache.
`output_tokens`required	`integer` Output tokens, reasoning included.
`cache_read_input_tokens`required	`integer`
`cache_creation_input_tokens`required	`integer`
`reasoning_tokens`required	`integer \| null`
`estimated`required	`boolean` True when the provider reported no usage and the gateway counted.
`raw`required	`object \| null` The provider's usage object, as it sent it.

`Finding`

`object`required	`"finding"`
`id`required	`FindingId`
`guardrail`required	`Guardrail`
`kind`required	`string` What the detector found, such as `aws_access_key`, `email`, `instruction_override` or `weapons`.
`action`required	`"record" \| "redact" \| "pseudonymize" \| "block" \| "flag" \| "cut"`
`mode`required	`GuardrailMode`
`applied`required	`boolean` False in monitor mode, where the action is only recorded.
`block`required	`integer`
`part`required	`Part`

`RequestList`

`object`required	`"list"`
`data`required	`Request[]`
`list_metadata`required	`ListMetadata`

`ContentRead`

`object`required	`"content_read"`
`request_id`required	`RequestId`
`version`required	`ContentVersion \| null`
`attachment`required	`string \| null` The attachment's hash, when one was read.
`reader`required	`Actor`

`FindingsSummary`

objectrequired "findings_summary"

fromrequired Timestamp

torequired Timestamp

groupsrequired

object[]

Each item

`guardrail`required	`Guardrail`
`kind`required	`string`
`action`required	`string`
`mode`required	`GuardrailMode`
`count`required	`integer`
`requests`required	`integer` Distinct requests, each counted once however often a block was resent.
`samples`required	`RequestId[]`

`Disposition`

`object`required	`"disposition"`
`id`required	`DispositionId`
`finding_id`required	`FindingId`
`label`required	`"false_positive" \| "confirmed"`
`note`required	`string \| null`
`created_by`required	`Actor`
`created_at`required	`Timestamp`

`DispositionCreate`

`label`required	`"false_positive" \| "confirmed"`
`note`	`string`

`DispositionList`

`object`required	`"list"`
`data`required	`Disposition[]`
`list_metadata`required	`ListMetadata`

`Totals`

requestsrequired integer

verdictsrequired

object

Fields

`passed`required	`integer`
`modified`required	`integer`
`blocked`required	`integer`
`cut`required	`integer`

errorsrequired

integer

Requests whose provider failed.

input_tokensrequired integer

output_tokensrequired integer

costrequired Money

findingsrequired

object

Fields

`secrets`required	`integer`
`personal_data`required	`integer`
`prompt_injection`required	`integer`
`illegal_content`required	`integer`

organizationsrequired integer

usersrequired integer

modelsrequired

map<string, integer>

The requests a provider served, by the model they asked for.

providersrequired

map<string, integer>

The requests a provider served, by that provider.

`Summary`

objectrequired "summary"

fromrequired Timestamp

torequired Timestamp

intervalrequired "hour" | "day"

organization_idrequired OrganizationId | null

user_idrequired UserId | null

totalsrequired Totals

seriesrequired

object[]

Each item

`start`required	`Timestamp`
`totals`required	`Totals`

`SummaryList`

`object`required	`"list"`
`data`required	`Summary[]`
`list_metadata`required	`ListMetadata`

`SignalState`

"open" | "dismissed" | "actioned"

`Signal`

objectrequired "signal"

idrequired SignalId

kindrequired

string

What was observed, such as injection_attempts, illegal_content, secret_probing, shared_template, topic_variety (far more conversations in an hour than the app's users hold) or shim_shape (requests whose parameters and client software the app's own traffic doesn't have, as an OpenAI-compatible shim's).

organizationrequired Ref | null

userrequired Ref | null

scorerequired number

windowrequired

object

Fields

`from`required	`Timestamp`
`to`required	`Timestamp`

evidencerequired

object

Fields

`requests`required	`RequestId[]`
`features`required	`map<string, number>`

staterequired SignalState

created_atrequired Timestamp

updated_atrequired Timestamp

`SignalList`

`object`required	`"list"`
`data`required	`Signal[]`
`list_metadata`required	`ListMetadata`

`EventType`

`Event`

`object`required	`"event"`
`id`required	`EventId`
`event`required	`EventType`
`data`required	`object` The object the event is about, as it was then.
`actor`required	`Actor \| null` Who caused it, or null when traffic did.
`environment_id`required	`EnvironmentId`
`created_at`required	`Timestamp`

`EventList`

`object`required	`"list"`
`data`required	`Event[]`
`list_metadata`required	`ListMetadata`

`LimitThreshold`

objectrequired "limit_threshold"

limitrequired

object

Fields

`kind`required	`"requests" \| "tokens" \| "spend"`
`per`required	`LimitScope`
`period`required	`"minute" \| "day" \| "week" \| "month"`
`amount`required	`string` As a decimal string for every kind.

organizationrequired Ref | null

userrequired Ref | null

thresholdrequired

80 | 95 | 100

The percentage crossed; 100 when the limit starts refusing.

usedrequired string

resets_atrequired Timestamp

`WebhookEndpointState`

"enabled" | "disabled"

`WebhookEndpoint`

`object`required	`"webhook_endpoint"`
`id`required	`WebhookEndpointId`
`url`required	`string (uri)`
`events`required	`EventType[]` The events it receives; empty for all of them.
`state`required	`WebhookEndpointState`
`disabled_reason`required	`"deliveries_failing" \| "disabled_by_team" \| null`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`WebhookEndpointWithSecret`

WebhookEndpoint & object

`WebhookEndpointCreate`

`url`required	`string (uri)`
`events`	`EventType[]` 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.

`WebhookEndpointUpdate`

`url`	`string (uri)`
`events`	`EventType[]`
`state`	`WebhookEndpointState`

`WebhookEndpointList`

`object`required	`"list"`
`data`required	`WebhookEndpoint[]`
`list_metadata`required	`ListMetadata`

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

idrequired DeliveryId

webhook_endpoint_idrequired WebhookEndpointId

event_idrequired EventId

eventrequired EventType

staterequired DeliveryState

attemptsrequired

object[]

Each item

`at`required	`Timestamp`
`status`required	`integer \| null`
`duration_ms`required	`number`
`error`required	`string \| null` Such as `timeout`, `connection_refused` or `tls_error`.

next_attempt_atrequired string (date-time) | null

created_atrequired Timestamp

`DeliveryList`

`object`required	`"list"`
`data`required	`Delivery[]`
`list_metadata`required	`ListMetadata`

`JobState`

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

`Replay`

objectrequired "replay"

idrequired ReplayId

staterequired JobState

policyrequired

object

The draft that was replayed.

Fields

`policy_id`	`PolicyId \| null`
`match`required	`Match`
`settings`required	`Settings`

fromrequired Timestamp

torequired Timestamp

progressrequired number

resultrequired

object | null

What would have changed. Null until completed.

errorrequired string | null

created_byrequired Actor

created_atrequired Timestamp

completed_atrequired string (date-time) | null

`ReplayCreate`

A new draft (match and settings), or changes to an existing policy (policy_id with either).

`policy_id`	`PolicyId`
`match`	`Match`
`settings`	`Settings`
`from`required	`Timestamp`
`to`required	`Timestamp`

`EvidencePack`

`object`required	`"evidence_pack"`
`id`required	`EvidencePackId`
`state`required	`JobState`
`organization_id`required	`OrganizationId`
`from`required	`Timestamp`
`to`required	`Timestamp`
`error`required	`string \| null`
`created_by`required	`Actor`
`created_at`required	`Timestamp`
`completed_at`required	`string (date-time) \| null`
`expires_at`required	`string (date-time) \| null` When the files are deleted, per the organization's retention.

`EvidencePackCreate`

`organization_id`required	`OrganizationId`
`from`required	`Timestamp`
`to`required	`Timestamp`

`Assessment`

`object`required	`"assessment"`
`id`required	`AssessmentId`
`name`required	`string`
`state`required	`"awaiting_upload" \| "queued" \| "running" \| "completed" \| "failed"`
`format`required	`AssessmentFormat`
`upload`required	`object \| null` Where to upload the logs, while the assessment awaits them.
`progress`required	`object \| null` Where the assessment is while it is queued or running, as of its last checkpoint: `null` until it has read its first part of the upload, and once it ends.
`error`required	`string \| null`
`created_by`required	`Actor`
`created_at`required	`Timestamp`
`completed_at`required	`string (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 model invocation logs as Bedrock writes them, the user, organization and plan taken from each invocation's requestMetadata (user, organization, plan), or the user from an Anthropic body's metadata.user_id. An upload is at most 5 GiB. 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. The hashes can be any stable hash the prospect chooses. Signals that read what users wrote (shared templates, prompt injection, secrets) are reported as unavailable for a metadata assessment.

`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_idrequired AssessmentId

namerequired string

formatrequired AssessmentFormat

fromrequired

string (date-time) | null

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

torequired

string (date-time) | null

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

generated_atrequired Timestamp

rowsrequired

object

Fields

`read`required	`integer` Lines that weren't blank.
`accepted`required	`integer`
`rejected`required	`map<string, integer>` Rows rejected, by why.

users_analyzedrequired integer

suspicious_usersrequired integer

tokensrequired

object

Fields

`total`required	`integer`
`suspicious`required	`integer`

suspicious_token_sharerequired number

estimated_costrequired

object

In US dollars, at list prices.

Fields

`total`required	`Decimal`
`suspicious`required	`Decimal`

usersrequired

object[]

The most suspicious users, most suspicious first.

Each item

userrequired

string

The user's id as the upload names it.

organizationrequired string | null

planrequired string | null

scorerequired number

requestsrequired integer

tokensrequired integer

estimated_costrequired Decimal

signalsrequired

object[]

Each item

`kind`required	`string` As a signal's `kind`, such as `shared_template`.
`score`required	`number`
`lines`required	`integer[]` Lines of the upload behind the signal.

unavailable_signalsrequired

string[]

Signals the assessment couldn't look for: those that read what users wrote, for a metadata assessment. Empty for the provider formats.

`AssessmentCreate`

`name`required	`string`
`format`required	`AssessmentFormat`

`Role`

"admin" | "developer" | "viewer"

`Team`

`object`required	`"team"`
`id`required	`TeamId`
`name`required	`string`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`TeamUpdate`

`name`	`string`

`Member`

`object`required	`"member"`
`id`required	`MemberId`
`email`required	`string (email)`
`name`required	`string \| null`
`role`required	`Role`
`state`required	`"invited" \| "active"`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`MemberUpdate`

`role`required	`Role`

`InvitationCreate`

`email`required	`string (email)`
`role`required	`Role`

`MemberList`

`object`required	`"list"`
`data`required	`Member[]`
`list_metadata`required	`ListMetadata`

`Project`

`object`required	`"project"`
`id`required	`ProjectId`
`name`required	`string`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`ProjectCreate`

`name`required	`string`

`ProjectUpdate`

`name`	`string`

`ProjectList`

`object`required	`"list"`
`data`required	`Project[]`
`list_metadata`required	`ListMetadata`

`Environment`

`object`required	`"environment"`
`id`required	`EnvironmentId`
`project_id`required	`ProjectId`
`name`required	`string`
`region`required	`Region`
`production`required	`boolean` Production environments' keys say `live`; the rest say `test`.
`api_base_url`required	`string`
`gateway_base_url`required	`string`
`created_at`required	`Timestamp`
`updated_at`required	`Timestamp`

`EnvironmentCreate`

`project_id`required	`ProjectId`
`name`required	`string`
`region`required	`Region`
`production`required	`boolean`

`EnvironmentUpdate`

`name`	`string`

`EnvironmentList`

`object`required	`"list"`
`data`required	`Environment[]`
`list_metadata`required	`ListMetadata`

Management API reference

Overview

Hosts

Authentication

Conventions

Webhooks

Errors

Organizations

GET/organizations

POST/organizations

GET/organizations/{id}

PATCH/organizations/{id}

DELETE/organizations/{id}

GET/organizations/external_id/{external_id}

Users

GET/users

POST/users

GET/users/{id}

PATCH/users/{id}

GET/users/external_id/{external_id}

GET/related_users

GET/organization_memberships

Suspensions

GET/suspensions

POST/suspensions

GET/suspensions/{id}

POST/suspensions/{id}/lift

Policies

GET/policies

POST/policies

GET/policies/{id}

PATCH/policies/{id}

DELETE/policies/{id}

GET/policies/{id}/versions

GET/effective_policy

Connections

GET/connections

POST/connections

GET/connections/{id}

PATCH/connections/{id}

DELETE/connections/{id}

POST/connections/{id}/test

Content store

GET/content_store

POST/content_store

DELETE/content_store

POST/content_store/test

API keys

GET/api_keys

POST/api_keys

GET/api_keys/{id}

PATCH/api_keys/{id}

DELETE/api_keys/{id}

POST/api_keys/{id}/rotate

Requests

GET/requests

GET/requests/{id}

GET/requests/{id}/content

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

GET/requests/{id}/conversation

Findings

GET/findings/summary

GET/findings/{id}/dispositions

POST/findings/{id}/dispositions

Summaries

GET/summary

GET/summary/users

Signals

GET/signals

GET/signals/{id}

POST/signals/{id}/dismiss

System prompts

GET/system_prompts

POST/system_prompts

GET/system_prompts/{id}

DELETE/system_prompts/{id}

Events

GET/events

GET/events/{id}

Webhooks

GET`/organizations`

POST`/organizations`

GET`/organizations/{id}`

PATCH`/organizations/{id}`

DELETE`/organizations/{id}`

GET`/organizations/external_id/{external_id}`

GET`/users`

POST`/users`

GET`/users/{id}`

PATCH`/users/{id}`

GET`/users/external_id/{external_id}`

GET`/related_users`

GET`/organization_memberships`

GET`/suspensions`

POST`/suspensions`

GET`/suspensions/{id}`

POST`/suspensions/{id}/lift`

GET`/policies`

POST`/policies`

GET`/policies/{id}`

PATCH`/policies/{id}`

DELETE`/policies/{id}`

GET`/policies/{id}/versions`

GET`/effective_policy`

GET`/connections`

POST`/connections`

GET`/connections/{id}`

PATCH`/connections/{id}`

DELETE`/connections/{id}`

POST`/connections/{id}/test`

GET`/content_store`

POST`/content_store`

DELETE`/content_store`

POST`/content_store/test`

GET`/api_keys`

POST`/api_keys`

GET`/api_keys/{id}`

PATCH`/api_keys/{id}`

DELETE`/api_keys/{id}`

POST`/api_keys/{id}/rotate`

GET`/requests`

GET`/requests/{id}`

GET`/requests/{id}/content`

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

GET`/requests/{id}/conversation`

GET`/findings/summary`

GET`/findings/{id}/dispositions`

POST`/findings/{id}/dispositions`

GET`/summary`

GET`/summary/users`

GET`/signals`

GET`/signals/{id}`

POST`/signals/{id}/dismiss`

GET`/system_prompts`

POST`/system_prompts`

GET`/system_prompts/{id}`

DELETE`/system_prompts/{id}`

GET`/events`

GET`/events/{id}`

GET`/webhook_endpoints`

POST`/webhook_endpoints`

GET`/webhook_endpoints/{id}`

PATCH`/webhook_endpoints/{id}`

DELETE`/webhook_endpoints/{id}`

POST`/webhook_endpoints/{id}/rotate_secret`

POST`/webhook_endpoints/{id}/test`

GET`/webhook_endpoints/{id}/deliveries`

POST`/deliveries/{id}/retry`

POST`/replays`

GET`/replays/{id}`

POST`/evidence_packs`

GET`/evidence_packs/{id}`

GET`/evidence_packs/{id}/download`

POST`/assessments`

GET`/assessments/{id}`

GET`/assessments/{id}/report`

GET`/team`

PATCH`/team`

GET`/team/members`

PATCH`/team/members/{id}`