agent-extras

Agent registration, invites, key rotation, security posture, and the registration-event audit log — the agent surface beyond the lifecycle core.

Amfelt REST API · v1.13.0 · https://api.amfelt.com

GET `/v1/agents/registration-events`

List registration events.

Returns the agent-registration audit log for the caller’s organization. Newest first; the agent_id query param filters to events for a single agent.

Parameters

Name	In	Required	Type	Description
`X-Tenant-Slug`	header	Yes	string	Slug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
`agent_id`	query	No	string	Filter registration events by agent identifier.
Filter registration events by agent identifier.
`cursor`	query	No	string	Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
`limit`	query	No	integer	Maximum number of items to return per page.
Maximum number of items to return per page.

Responses

200 A page of registration-event audit rows.

application/json

Property	Type	Required	Description
`data`	RegistrationEvent []	Yes	The page of events.
The page of events.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/agents/register`

Registers a new agent against a pre-shared invite code. The body’s code is the authentication; no JWT is required. Returns 201 with status “active” on auto-activation, or 202 with status “pending_approval” plus poll_url when the invite requires admin review.

Request body (required)

application/json

Property	Type	Required	Description
`capabilities`	string[]	No	Optional capability strings reported by the agent.
Optional capability strings reported by the agent.
`code`	string	Yes	Pre-shared registration code (from a minted invite).
Pre-shared registration code (from a minted invite).
`hostname`	string	No	Agent’s host name; reported at handshake.
Agent’s host name; reported at handshake.
`public_key_pem`	string	Yes	PEM-encoded Ed25519 public key the agent will use to authenticate.
PEM-encoded Ed25519 public key the agent will use to authenticate.
`version`	string	No	Agent’s semantic version at registration.
Agent’s semantic version at registration.

Responses

201 The agent was registered and is active.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Unique identifier of the registered agent.
Unique identifier of the registered agent.
`display_name`	string	Yes	Human-readable name pinned at registration.
Human-readable name pinned at registration.
`poll_url`	string	No	Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
`status`	AgentLifecycleStatus	Yes

`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.

202 The agent was registered and is pending admin approval.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Unique identifier of the registered agent.
Unique identifier of the registered agent.
`display_name`	string	Yes	Human-readable name pinned at registration.
Human-readable name pinned at registration.
`poll_url`	string	No	Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
`status`	AgentLifecycleStatus	Yes

`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

GET `/v1/agents/invites`

List agent invites.

Returns pending and recently-consumed agent invites for the caller’s organization, newest first.

Parameters

Name	In	Required	Type	Description
`X-Tenant-Slug`	header	Yes	string	Slug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
`cursor`	query	No	string	Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
`limit`	query	No	integer	Maximum number of items to return per page.
Maximum number of items to return per page.

Responses

200 A page of agent invites.

application/json

Property	Type	Required	Description
`data`	AgentInvite []	Yes	The page of invites.
The page of invites.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/agents/invite`

Create an agent invite.

Mints a pre-shared registration code for the caller’s organization. The raw token is returned ONCE in the response — subsequent reads only return token_hint.

Parameters

Name	In	Required	Type	Description
`X-Tenant-Slug`	header	Yes	string	Slug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.

Request body (required)

application/json

Property	Type	Required	Description
`approval_required`	boolean	Yes	Whether the resulting agent must wait for admin approval.
Whether the resulting agent must wait for admin approval.
`display_name`	string	Yes	Human-readable name to pin on the registering agent.
Human-readable name to pin on the registering agent.
`ttl_seconds`	integer	No	Override the default 24h validity window; capped server-side at 7 days.
Override the default 24h validity window; capped server-side at 7 days.

Responses

201 The invite was created.

application/json

Property	Type	Required	Description
`approval_required`	boolean	Yes	Whether the resulting agent will wait for admin approval.
Whether the resulting agent will wait for admin approval.
`display_name`	string	Yes	Human-readable name pinned on the eventual agent.
Human-readable name pinned on the eventual agent.
`expires_at`	string	Yes	Timestamp the invite expires.
Timestamp the invite expires.
`invite_id`	string	Yes	Identifier of the invite.
Identifier of the invite.
`invite_token`	string	Yes	The raw token; returned once, never persisted in cleartext.
The raw token; returned once, never persisted in cleartext.
`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`token_hint`	string	Yes	First characters of the invite token, for display.
First characters of the invite token, for display.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/agents/{agent_id}/security-posture`

Get an agent's security posture.

Returns the agent’s lifecycle status, liveness, key fingerprint, version, expected operational tier, and last-seen time. Used by the doctor cross-check.

Parameters

Name	In	Required	Type	Description
`X-Tenant-Slug`	header	Yes	string	Slug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
`agent_id`	path	Yes	string	Identifier of the agent.
Identifier of the agent.

Responses

200 The agent's security posture.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`expected_tier`	string	Yes	Operational tier the agent is expected to be at (e.g. “stable”, “edge”).
Operational tier the agent is expected to be at (e.g. “stable”, “edge”).
`key_fingerprint`	string	No	Fingerprint of the agent’s bound public key.
Fingerprint of the agent’s bound public key.
`last_seen_at`	string	No	Timestamp the agent was last seen; absent if it has never connected.
Timestamp the agent was last seen; absent if it has never connected.
`liveness`	string	Yes	Liveness derived from the agent’s last-seen time. Valid values are: `online`, `offline`, `never_seen`. Examples: `online`.
Liveness derived from the agent’s last-seen time. Valid values are: `online`, `offline`, `never_seen`. Examples: `online`.
`status`	AgentLifecycleStatus	Yes

`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`version`	string	No	Semantic version reported by the agent at last handshake.
Semantic version reported by the agent at last handshake.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/agents/{agent_id}/key`

Rotate an agent's key.

Binds a new Ed25519 public key to the agent. The previous key signs the request (verified inline); the new key takes effect on the next handshake.

Parameters

Name	In	Required	Type	Description
`agent_id`	path	Yes	string	Identifier of the agent.
Identifier of the agent.

Request body (required)

application/json

Property	Type	Required	Description
`new_public_key_pem`	string	Yes	PEM-encoded Ed25519 public key to bind to the agent going forward.
PEM-encoded Ed25519 public key to bind to the agent going forward.

Responses

200 The key was rotated (or no-op if the same key was presented).

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent whose key was rotated.
Identifier of the agent whose key was rotated.
`new_fingerprint`	string	Yes	Fingerprint of the key now bound to the agent.
Fingerprint of the key now bound to the agent.
`old_fingerprint`	string	Yes	Fingerprint of the key that was bound before the rotation.
Fingerprint of the key that was bound before the rotation.
`rotated`	boolean	Yes	True when the key changed; false on a no-op (same key presented).
True when the key changed; false on a no-op (same key presented).

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/agents/invites/{invite_id}`

Revoke an agent invite.

Revokes a pending agent invite so its code can no longer be used.

Parameters

Name	In	Required	Type	Description
`X-Tenant-Slug`	header	Yes	string	Slug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
`invite_id`	path	Yes	string	Identifier of the invite.
Identifier of the invite.

Responses

204 The invite was revoked.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

Schemas

Registration Event List

type: RegistrationEventList

A page of registration-event audit rows.

Property	Type	Required	Description
`data`	RegistrationEvent []	Yes	The page of events.
The page of events.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

Registration Event

type: RegistrationEvent

A single row in the agent-registration audit log.

Property	Type	Required	Description
`actor`	string	No	Actor identifier (admin user or agent).
Actor identifier (admin user or agent).
`agent_id`	string	No	Identifier of the agent (absent for invite-creation events).
Identifier of the agent (absent for invite-creation events).
`created_at`	string	Yes	Timestamp the event was recorded.
Timestamp the event was recorded.
`event_type`	string	Yes	The kind of event recorded (e.g. registered, approved, rejected).
The kind of event recorded (e.g. registered, approved, rejected).
`id`	string	Yes	Identifier of the audit row.
Identifier of the audit row.
`invite_id`	string	No	Identifier of the invite (absent for events not tied to one).
Identifier of the invite (absent for events not tied to one).
`reason`	string	No	Reason classifier; populated for rejects and same-actor blocks.
Reason classifier; populated for rejects and same-actor blocks.
`source_ip`	string	No	Source IP of the request that produced the event.
Source IP of the request that produced the event.
`tenant_id`	string	Yes	Identifier of the organization the event belongs to.
Identifier of the organization the event belongs to.
`user_agent`	string	No	User-Agent header of the request that produced the event.
User-Agent header of the request that produced the event.

Error

type: Error

The standard error envelope returned by every non-2xx response.

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Agent Registration

type: AgentRegistration

The payload for POST /v1/agents/register.

Property	Type	Required	Description
`capabilities`	string[]	No	Optional capability strings reported by the agent.
Optional capability strings reported by the agent.
`code`	string	Yes	Pre-shared registration code (from a minted invite).
Pre-shared registration code (from a minted invite).
`hostname`	string	No	Agent’s host name; reported at handshake.
Agent’s host name; reported at handshake.
`public_key_pem`	string	Yes	PEM-encoded Ed25519 public key the agent will use to authenticate.
PEM-encoded Ed25519 public key the agent will use to authenticate.
`version`	string	No	Agent’s semantic version at registration.
Agent’s semantic version at registration.

Registration Result

type: RegistrationResult

Result of POST /v1/agents/register. Status is “active” on auto-activation (201) or “pending_approval” on invites that require admin review (202).

Property	Type	Required	Description
`agent_id`	string	Yes	Unique identifier of the registered agent.
Unique identifier of the registered agent.
`display_name`	string	Yes	Human-readable name pinned at registration.
Human-readable name pinned at registration.
`poll_url`	string	No	Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
Polling endpoint to wait for admin approval; populated when status is “pending_approval” (HTTP 202).
`status`	AgentLifecycleStatus	Yes

`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.

Agent Lifecycle Status

type: AgentLifecycleStatus

Lifecycle status of an agent.

Agent Invite List

type: AgentInviteList

A page of agent invites.

Property	Type	Required	Description
`data`	AgentInvite []	Yes	The page of invites.
The page of invites.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

Agent Invite

type: AgentInvite

A pending or consumed agent invite.

Property	Type	Required	Description
`agent_id`	string	No	Identifier of the agent that consumed the invite (absent until consumed).
Identifier of the agent that consumed the invite (absent until consumed).
`approval_required`	boolean	Yes	Whether the resulting agent will wait for admin approval.
Whether the resulting agent will wait for admin approval.
`consumed_at`	string	No	Timestamp the invite was consumed (absent for pending invites).
Timestamp the invite was consumed (absent for pending invites).
`created_at`	string	Yes	Timestamp the invite was created.
Timestamp the invite was created.
`created_by`	string	No	Identifier of the admin user that minted the invite.
Identifier of the admin user that minted the invite.
`display_name`	string	Yes	Human-readable name pinned on the eventual agent.
Human-readable name pinned on the eventual agent.
`expires_at`	string	Yes	Timestamp the invite expires.
Timestamp the invite expires.
`id`	string	Yes	Identifier of the invite.
Identifier of the invite.
`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`token_hint`	string	Yes	First characters of the invite token, for display.
First characters of the invite token, for display.

Agent Invite Create

type: AgentInviteCreate

The payload for POST /v1/agents/invite.

Property	Type	Required	Description
`approval_required`	boolean	Yes	Whether the resulting agent must wait for admin approval.
Whether the resulting agent must wait for admin approval.
`display_name`	string	Yes	Human-readable name to pin on the registering agent.
Human-readable name to pin on the registering agent.
`ttl_seconds`	integer	No	Override the default 24h validity window; capped server-side at 7 days.
Override the default 24h validity window; capped server-side at 7 days.

Agent Invite Created

type: AgentInviteCreated

A newly created agent invite. The raw token is returned ONCE — store it immediately; subsequent reads only expose token_hint.

Property	Type	Required	Description
`approval_required`	boolean	Yes	Whether the resulting agent will wait for admin approval.
Whether the resulting agent will wait for admin approval.
`display_name`	string	Yes	Human-readable name pinned on the eventual agent.
Human-readable name pinned on the eventual agent.
`expires_at`	string	Yes	Timestamp the invite expires.
Timestamp the invite expires.
`invite_id`	string	Yes	Identifier of the invite.
Identifier of the invite.
`invite_token`	string	Yes	The raw token; returned once, never persisted in cleartext.
The raw token; returned once, never persisted in cleartext.
`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`token_hint`	string	Yes	First characters of the invite token, for display.
First characters of the invite token, for display.

Agent Security Posture

type: AgentSecurityPosture

Security posture of an agent — used by the doctor cross-check.

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`expected_tier`	string	Yes	Operational tier the agent is expected to be at (e.g. “stable”, “edge”).
Operational tier the agent is expected to be at (e.g. “stable”, “edge”).
`key_fingerprint`	string	No	Fingerprint of the agent’s bound public key.
Fingerprint of the agent’s bound public key.
`last_seen_at`	string	No	Timestamp the agent was last seen; absent if it has never connected.
Timestamp the agent was last seen; absent if it has never connected.
`liveness`	string	Yes	Liveness derived from the agent’s last-seen time. Valid values are: `online`, `offline`, `never_seen`. Examples: `online`.
Liveness derived from the agent’s last-seen time. Valid values are: `online`, `offline`, `never_seen`. Examples: `online`.
`status`	AgentLifecycleStatus	Yes

`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`version`	string	No	Semantic version reported by the agent at last handshake.
Semantic version reported by the agent at last handshake.

Key Rotation

type: KeyRotation

The payload for PUT /v1/agents/{agent_id}/key.

Property	Type	Required	Description
`new_public_key_pem`	string	Yes	PEM-encoded Ed25519 public key to bind to the agent going forward.
PEM-encoded Ed25519 public key to bind to the agent going forward.

Key Rotation Result

type: KeyRotationResult

Result of an agent key rotation.

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent whose key was rotated.
Identifier of the agent whose key was rotated.
`new_fingerprint`	string	Yes	Fingerprint of the key now bound to the agent.
Fingerprint of the key now bound to the agent.
`old_fingerprint`	string	Yes	Fingerprint of the key that was bound before the rotation.
Fingerprint of the key that was bound before the rotation.
`rotated`	boolean	Yes	True when the key changed; false on a no-op (same key presented).
True when the key changed; false on a no-op (same key presented).

Last updated on October 31, 2026

Docs

agent-extras

GET /v1/agents/registration-events

Parameters

Responses

Security

POST /v1/agents/register

Request body (required)

Responses

GET /v1/agents/invites

Parameters

Responses

Security

POST /v1/agents/invite

Parameters

Request body (required)

Responses

Security

GET /v1/agents/{agent_id}/security-posture

Parameters

Responses

Security

PUT /v1/agents/{agent_id}/key

Parameters

Request body (required)

Responses

Security

DELETE /v1/agents/invites/{invite_id}

Parameters

Responses

Security

Schemas

Registration Event List

Registration Event

Error

Agent Registration

Registration Result

Agent Lifecycle Status

Agent Invite List

Agent Invite

Agent Invite Create

Agent Invite Created

Agent Security Posture

Key Rotation

Key Rotation Result

On this page

GET `/v1/agents/registration-events`

POST `/v1/agents/register`

GET `/v1/agents/invites`

POST `/v1/agents/invite`

GET `/v1/agents/{agent_id}/security-posture`

PUT `/v1/agents/{agent_id}/key`

DELETE `/v1/agents/invites/{invite_id}`