agent

Registered Amfelt agents and their approval lifecycle.

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

GET `/v1/agents`

List agents.

Returns a page of agents registered to the caller’s organization, optionally filtered by status.

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.
`status`	query	No	string[]	Filter agents by status; repeat the parameter to pass multiple values.
Filter agents by status; repeat the parameter to pass multiple values.
`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 agents.

application/json

Property	Type	Required	Description
`data`	Agent []	Yes	The page of agents.
The page of agents.
`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`.

Security

bearer_jwt

POST `/v1/agents/{agent_id}/upgrade`

Upgrade an agent to a published release, the newest by default.

Asks the agent to replace its own binary with a published, non-prerelease release and restart into it. The optional body names the target version. When the body or its version is absent, the target is the newest release, which is the same value version skew is derived against. The agent’s effective target is the version its environments’ policies derive, the strictest of them winning (the agent’s target_version). A version lower than the running version moves the agent down, which this operation does in one case only: the agent’s target_state is rollback_pending and version equals its effective target. That is the manual retry of the downgrade the orchestrator applies once the agent is idle, and it needs no permission beyond agents.upgrade. Any other lower version is refused with downgrade_requires_rollback: an agent moves down only after a rollback of its environment’s pin (changeAgentVersionPolicy with rollback: true). A manual upgrade to the effective target, the rollback retry included, is also the retry of a failed upgrade: it clears the pause that failure set (the agent’s upgrade_paused). A manual upgrade to any other version leaves the pause in place and also needs the agents.versions.manage permission. The pause itself is never a reason to refuse a manual upgrade; every other refusal still applies. Only agents reporting the native deployment mode are eligible. Every other mode — including unknown — is owned by an orchestrator or a package manager that would overwrite the change, so the request is refused rather than attempted.

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.

Request body

application/json

Property	Type	Required	Description
`version`	string	No	The published, non-prerelease release to install. A version below the running one is refused with `downgrade_requires_rollback`, unless it is the agent’s effective target and the agent’s `target_state` is `rollback_pending`. Examples: `5.1.3`.
The published, non-prerelease release to install. A version below the running one is refused with `downgrade_requires_rollback`, unless it is the agent’s effective target and the agent’s `target_state` is `rollback_pending`. Examples: `5.1.3`.

Responses

202 The upgrade was dispatched to the agent. The body carries the correlation id every outcome for this dispatch is keyed by — the operator-visible result arrives later on the agent's `last_command`, not in this response. A `queued_offline` status means the agent was not connected and the frame was persisted, so that result may be minutes rather than seconds away.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes

`id`	string	Yes	Correlation id — matches the event frames this command produces.
Correlation id — matches the event frames this command produces.
`status`	string	Yes	`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`type`	string	Yes	Examples: `cmd.upgrade`.
Examples: `cmd.upgrade`.

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

409 The agent cannot be upgraded in its current state.

application/json

Property	Type	Required	Description
`message`	string	Yes	Human-readable explanation, safe to show an operator. Examples: `This agent runs in a container; upgrade its image instead.`.
Human-readable explanation, safe to show an operator. Examples: `This agent runs in a container; upgrade its image instead.`.
`reason`	string	Yes	Machine-readable refusal reason. `upgrade_externally_managed` — the agent’s platform owns its binary and would overwrite the change; `message` names what to update instead. `upgrade_agent_unreachable` — the agent is not currently connected, so the command could not be delivered. Retry when it reconnects. `upgrade_agent_busy` — the agent is connected but a run is in flight. Retry when it is idle. `upgrade_not_needed` — there is nothing to upgrade to, either because the agent already runs the target release or because the newest release could not be determined. `approval_required` — the target is above the version a pinned environment of the agent holds. That pin must move first, through changeAgentVersionPolicy: a change to Production applies once its approval request is approved, and a change to any other environment applies at once. `downgrade_requires_rollback` — the target is below the running version and is not a downgrade the agent is due. Only the effective target of an agent whose `target_state` is `rollback_pending` moves it down: an agent moves down only after a rollback of its environment’s pin. Valid values are: `upgrade_externally_managed`, `upgrade_agent_unreachable`, `upgrade_agent_busy`, `upgrade_not_needed`, `approval_required`, `downgrade_requires_rollback`. Examples: `upgrade_externally_managed`.
Machine-readable refusal reason. `upgrade_externally_managed` — the agent’s platform owns its binary and would overwrite the change; `message` names what to update instead. `upgrade_agent_unreachable` — the agent is not currently connected, so the command could not be delivered. Retry when it reconnects. `upgrade_agent_busy` — the agent is connected but a run is in flight. Retry when it is idle. `upgrade_not_needed` — there is nothing to upgrade to, either because the agent already runs the target release or because the newest release could not be determined. `approval_required` — the target is above the version a pinned environment of the agent holds. That pin must move first, through changeAgentVersionPolicy: a change to Production applies once its approval request is approved, and a change to any other environment applies at once. `downgrade_requires_rollback` — the target is below the running version and is not a downgrade the agent is due. Only the effective target of an agent whose `target_state` is `rollback_pending` moves it down: an agent moves down only after a rollback of its environment’s pin. Valid values are: `upgrade_externally_managed`, `upgrade_agent_unreachable`, `upgrade_agent_busy`, `upgrade_not_needed`, `approval_required`, `downgrade_requires_rollback`. Examples: `upgrade_externally_managed`.

422 The named `version` is not a published, non-prerelease release.

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}/status`

Get agent status.

Returns the current status and last-seen time of an agent. Public: a pending agent polls this before it holds any credentials.

Parameters

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

Responses

200 The agent status.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`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.
`status`	AgentLifecycleStatus	Yes

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

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

POST `/v1/agents/{agent_id}/reject`

Reject an agent.

Transitions a pending agent to the revoked state. A reason is required and recorded in the audit trail.

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.

Request body (required)

application/json

Property	Type	Required	Description
`reason`	string	Yes	Reason for the rejection; recorded in the audit trail.
Reason for the rejection; recorded in the audit trail.

Responses

200 The agent was rejected.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`status`	AgentLifecycleStatus	Yes

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

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

Security

bearer_jwt

GET `/v1/agents/{agent_id}/icpc-events`

List ICPC events observed for an agent.

Returns the frames the agent sent that matched no registered handler, newest first. This is where a command’s outcome lands: refusals, smoke-test failures and restart failures all arrive as error frames and are readable only here. A caller who does not hold both projects.update and sources.write reads some answer frames without their payload, marked payload_withheld; IcpcEvent.payload says which.

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.
`limit`	query	No	integer	Maximum number of events to return.
Maximum number of events to return.
`type`	query	No	string	Return only events of this exact frame type.
Return only events of this exact frame type.

Responses

200 The agent's observed ICPC events.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes

`count`	integer	Yes	Number of events in this response, after the limit is applied.
Number of events in this response, after the limit is applied.
`events`	IcpcEvent []	Yes

`total`	integer	Yes	Total events stored for this agent, ignoring the limit.
Total events stored for this agent, ignoring the limit.

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

POST `/v1/agents/{agent_id}/icpc-cmd`

Dispatch an ICPC command to a connected agent.

Queues a command frame on the agent’s live ICPC connection. The 202 means the frame was queued for delivery, not that the agent accepted or completed it: everything the agent decides afterwards travels back as an ICPC event, readable via /icpc-events. The type must name a cmd.* frame. The payload is opaque to the api — the agent-side handler for that command type interprets it — so this endpoint reaches any command the agent implements, including ones a dedicated endpoint would refuse. The agent-side gate is what constrains that, not this route.

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.

Request body (required)

application/json

Property	Type	Required	Description
`id`	string	No	Correlation id for the command. The server assigns a UUID when omitted, and echoes it back so the caller can tie an event to this dispatch.
Correlation id for the command. The server assigns a UUID when omitted, and echoes it back so the caller can tie an event to this dispatch.
`payload`	object	No	Opaque command arguments. The api does not interpret this — the agent-side handler for `type` defines its shape.
Opaque command arguments. The api does not interpret this — the agent-side handler for `type` defines its shape.
`type`	string	Yes	The command frame type. Must be a `cmd.*` name the agent implements; anything else is rejected before dispatch. Examples: `cmd.upgrade`.
The command frame type. Must be a `cmd.*` name the agent implements; anything else is rejected before dispatch. Examples: `cmd.upgrade`.

Responses

202 The command frame was queued for delivery to the agent.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes

`id`	string	Yes	Correlation id — matches the event frames this command produces.
Correlation id — matches the event frames this command produces.
`status`	string	Yes	`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`type`	string	Yes	Examples: `cmd.upgrade`.
Examples: `cmd.upgrade`.

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 No agent with that id, or no active ICPC connection for it.

503 The connection's send buffer is full — the agent is connected but not draining frames.

Security

bearer_jwt

POST `/v1/agents/{agent_id}/approve`

Approve an agent.

Transitions a pending agent to the active state. The approver must differ from the user that created the agent’s invite.

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.

Request body

application/json

Property	Type	Required	Description
`reason`	string	No	Optional reason recorded in the audit trail.
Optional reason recorded in the audit trail.

Responses

200 The agent was approved.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`status`	AgentLifecycleStatus	Yes

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

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

Security

bearer_jwt

GET `/v1/agents/{agent_id}`

Get an agent.

Returns a single agent by identifier, including its bound public key.

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.

application/json

Property	Type	Required	Description
`created_at`	string	Yes	Timestamp the agent was registered.
Timestamp the agent was registered.
`deploy_mode`	string	No	How the agent was deployed, as it reported on its heartbeat. Absent when the agent has never reported one. ‘unknown’ means the agent reported but could not classify its own host. Valid values are: `native`, `docker`, `k8s`, `package_manager`, `unknown`. Examples: `docker`.
How the agent was deployed, as it reported on its heartbeat. Absent when the agent has never reported one. ‘unknown’ means the agent reported but could not classify its own host. Valid values are: `native`, `docker`, `k8s`, `package_manager`, `unknown`. Examples: `docker`.
`display_name`	string	Yes	Human-readable name of the agent.
Human-readable name of the agent.
`externally_managed`	boolean	No	True when the agent does not report the `native` deployment mode, so it never replaces its own binary: whatever manages its image, chart or package moves it to `target_version`. Its `target_state` is derived like any other agent’s.
True when the agent does not report the `native` deployment mode, so it never replaces its own binary: whatever manages its image, chart or package moves it to `target_version`. Its `target_state` is derived like any other agent’s.
`floor_version`	string	No	The version floor `upgrade_required_reason` refers to. Present only with `upgrade_required_reason`. Examples: `5.1.0`.
The version floor `upgrade_required_reason` refers to. Present only with `upgrade_required_reason`. Examples: `5.1.0`.
`id`	string	Yes	Unique identifier of the agent.
Unique identifier of the agent.
`key_fingerprint`	string	No	Fingerprint of the agent’s bound public key.
Fingerprint of the agent’s bound public key.
`last_command`	AgentCommandOutcome	No

`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`.
`policy_sources`	EnvironmentSlug []	No	The DTAP environments whose policies set `target_version`. Derived per request, never stored. Examples: `["production"]`.
The DTAP environments whose policies set `target_version`. Derived per request, never stored. Examples: `["production"]`.
`public_key_pem`	string	No	PEM-encoded Ed25519 public key bound to the agent; returned by the detail endpoint only.
PEM-encoded Ed25519 public key bound to the agent; returned by the detail endpoint only.
`status`	AgentLifecycleStatus	Yes

`target_state`	string	No	How the agent’s running `version` stands against `target_version`. Derived per request, never stored. `current` — the agent runs its target. `behind` — the agent runs below its target. `above_pin` — the agent runs above its target, and no rollback lowered that target, for example a fresh install of the newest release that joins a pinned environment. It is left there: nothing downgrades it automatically. `rollback_pending` — the agent runs above its target because a rollback lowered that target (changeAgentVersionPolicy with `rollback: true`), applied in Production once its approval request is approved and in any other environment as soon as an owner or admin makes it. The orchestrator downgrades the agent to its target once it is idle, audited as operation `rollback`; upgradeAgent to the target is the manual retry. `upgrade_required` — the running version or the target is below a version floor the api requires; `upgrade_required_reason` says which. The orchestrator moves an idle agent that reports the `native` deployment mode and is not `upgrade_paused` to `target_version` from three states only: `behind`, `rollback_pending`, and `upgrade_required` with `upgrade_required_reason` `agent_below_floor`, whose target is valid. It leaves an agent that is `current`, `above_pin`, or `upgrade_required` with `pin_below_floor`, whose pin must move first. An externally managed agent (`externally_managed`) is derived the same way, so it can be `behind` or `upgrade_required` too. Valid values are: `current`, `behind`, `above_pin`, `rollback_pending`, `upgrade_required`. Examples: `behind`.
How the agent’s running `version` stands against `target_version`. Derived per request, never stored. `current` — the agent runs its target. `behind` — the agent runs below its target. `above_pin` — the agent runs above its target, and no rollback lowered that target, for example a fresh install of the newest release that joins a pinned environment. It is left there: nothing downgrades it automatically. `rollback_pending` — the agent runs above its target because a rollback lowered that target (changeAgentVersionPolicy with `rollback: true`), applied in Production once its approval request is approved and in any other environment as soon as an owner or admin makes it. The orchestrator downgrades the agent to its target once it is idle, audited as operation `rollback`; upgradeAgent to the target is the manual retry. `upgrade_required` — the running version or the target is below a version floor the api requires; `upgrade_required_reason` says which. The orchestrator moves an idle agent that reports the `native` deployment mode and is not `upgrade_paused` to `target_version` from three states only: `behind`, `rollback_pending`, and `upgrade_required` with `upgrade_required_reason` `agent_below_floor`, whose target is valid. It leaves an agent that is `current`, `above_pin`, or `upgrade_required` with `pin_below_floor`, whose pin must move first. An externally managed agent (`externally_managed`) is derived the same way, so it can be `behind` or `upgrade_required` too. Valid values are: `current`, `behind`, `above_pin`, `rollback_pending`, `upgrade_required`. Examples: `behind`.
`target_version`	string	No	The agent’s effective target: the version its environments’ policies derive, the strictest of them winning (the lowest pinned version, otherwise the newest release once its settle delay has passed). Derived per request, never stored. Absent when it cannot be derived. Examples: `5.1.3`.
The agent’s effective target: the version its environments’ policies derive, the strictest of them winning (the lowest pinned version, otherwise the newest release once its settle delay has passed). Derived per request, never stored. Absent when it cannot be derived. Examples: `5.1.3`.
`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`updated_at`	string	No	Timestamp the agent was last modified; returned by the detail endpoint only.
Timestamp the agent was last modified; returned by the detail endpoint only.
`upgrade_failure_reason`	string	No	The classified reason the agent’s last upgrade failed. Present while `upgrade_paused` is true. It is a code the agent reported, for example `upgrade_smoke_test_failed` or `upgrade_wrong_version`, or `ack_timeout` when the agent never acknowledged the upgrade. Examples: `upgrade_smoke_test_failed`.
The classified reason the agent’s last upgrade failed. Present while `upgrade_paused` is true. It is a code the agent reported, for example `upgrade_smoke_test_failed` or `upgrade_wrong_version`, or `ack_timeout` when the agent never acknowledged the upgrade. Examples: `upgrade_smoke_test_failed`.
`upgrade_paused`	boolean	No	True when the agent’s last upgrade failed, so automatic upgrades for it are paused and it keeps running its current binary. A manual upgradeAgent to its `target_version` is the retry: it clears the pause. A manual upgrade to any other version leaves it set.
True when the agent’s last upgrade failed, so automatic upgrades for it are paused and it keeps running its current binary. A manual upgradeAgent to its `target_version` is the retry: it clears the pause. A manual upgrade to any other version leaves it set.
`upgrade_required_reason`	string	No	Why the agent is `upgrade_required`. Present only when `target_state` is `upgrade_required`. `agent_below_floor` — the running version is below `floor_version`. `pin_below_floor` — `target_version` is a pin below `floor_version`, for example a floor raised after the pin was saved. The pin moves only by a promotion, never automatically. Valid values are: `agent_below_floor`, `pin_below_floor`. Examples: `pin_below_floor`.
Why the agent is `upgrade_required`. Present only when `target_state` is `upgrade_required`. `agent_below_floor` — the running version is below `floor_version`. `pin_below_floor` — `target_version` is a pin below `floor_version`, for example a floor raised after the pin was saved. The pin moves only by a promotion, never automatically. Valid values are: `agent_below_floor`, `pin_below_floor`. Examples: `pin_below_floor`.
`version`	string	No	Semantic version reported by the agent at handshake.
Semantic version reported by the agent at handshake.
`version_skew`	string	No	Whether the agent’s reported version is behind the newest published agent release. Derived per request, never stored. ‘unknown’ when the agent has never reported a version or the release list is unavailable. Valid values are: `up_to_date`, `behind`, `ahead`, `unknown`. Examples: `behind`.
Whether the agent’s reported version is behind the newest published agent release. Derived per request, never stored. ‘unknown’ when the agent has never reported a version or the release list is unavailable. Valid values are: `up_to_date`, `behind`, `ahead`, `unknown`. Examples: `behind`.

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

DELETE `/v1/agents/{agent_id}`

Deregister an agent.

Transitions the agent to the revoked (terminal) state. A second attempt on an already-revoked agent returns 409.

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 was deregistered.

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`status`	AgentLifecycleStatus	Yes

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

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

Security

bearer_jwt

Schemas

Agent List

type: AgentList

A page of agents.

Property	Type	Required	Description
`data`	Agent []	Yes	The page of agents.
The page of agents.
`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

type: Agent

An Amfelt agent registered to an organization.

Property	Type	Required	Description
`created_at`	string	Yes	Timestamp the agent was registered.
Timestamp the agent was registered.
`deploy_mode`	string	No	How the agent was deployed, as it reported on its heartbeat. Absent when the agent has never reported one. ‘unknown’ means the agent reported but could not classify its own host. Valid values are: `native`, `docker`, `k8s`, `package_manager`, `unknown`. Examples: `docker`.
How the agent was deployed, as it reported on its heartbeat. Absent when the agent has never reported one. ‘unknown’ means the agent reported but could not classify its own host. Valid values are: `native`, `docker`, `k8s`, `package_manager`, `unknown`. Examples: `docker`.
`display_name`	string	Yes	Human-readable name of the agent.
Human-readable name of the agent.
`externally_managed`	boolean	No	True when the agent does not report the `native` deployment mode, so it never replaces its own binary: whatever manages its image, chart or package moves it to `target_version`. Its `target_state` is derived like any other agent’s.
True when the agent does not report the `native` deployment mode, so it never replaces its own binary: whatever manages its image, chart or package moves it to `target_version`. Its `target_state` is derived like any other agent’s.
`floor_version`	string	No	The version floor `upgrade_required_reason` refers to. Present only with `upgrade_required_reason`. Examples: `5.1.0`.
The version floor `upgrade_required_reason` refers to. Present only with `upgrade_required_reason`. Examples: `5.1.0`.
`id`	string	Yes	Unique identifier of the agent.
Unique identifier of the agent.
`key_fingerprint`	string	No	Fingerprint of the agent’s bound public key.
Fingerprint of the agent’s bound public key.
`last_command`	AgentCommandOutcome	No

`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`.
`policy_sources`	EnvironmentSlug []	No	The DTAP environments whose policies set `target_version`. Derived per request, never stored. Examples: `["production"]`.
The DTAP environments whose policies set `target_version`. Derived per request, never stored. Examples: `["production"]`.
`public_key_pem`	string	No	PEM-encoded Ed25519 public key bound to the agent; returned by the detail endpoint only.
PEM-encoded Ed25519 public key bound to the agent; returned by the detail endpoint only.
`status`	AgentLifecycleStatus	Yes

`target_state`	string	No	How the agent’s running `version` stands against `target_version`. Derived per request, never stored. `current` — the agent runs its target. `behind` — the agent runs below its target. `above_pin` — the agent runs above its target, and no rollback lowered that target, for example a fresh install of the newest release that joins a pinned environment. It is left there: nothing downgrades it automatically. `rollback_pending` — the agent runs above its target because a rollback lowered that target (changeAgentVersionPolicy with `rollback: true`), applied in Production once its approval request is approved and in any other environment as soon as an owner or admin makes it. The orchestrator downgrades the agent to its target once it is idle, audited as operation `rollback`; upgradeAgent to the target is the manual retry. `upgrade_required` — the running version or the target is below a version floor the api requires; `upgrade_required_reason` says which. The orchestrator moves an idle agent that reports the `native` deployment mode and is not `upgrade_paused` to `target_version` from three states only: `behind`, `rollback_pending`, and `upgrade_required` with `upgrade_required_reason` `agent_below_floor`, whose target is valid. It leaves an agent that is `current`, `above_pin`, or `upgrade_required` with `pin_below_floor`, whose pin must move first. An externally managed agent (`externally_managed`) is derived the same way, so it can be `behind` or `upgrade_required` too. Valid values are: `current`, `behind`, `above_pin`, `rollback_pending`, `upgrade_required`. Examples: `behind`.
How the agent’s running `version` stands against `target_version`. Derived per request, never stored. `current` — the agent runs its target. `behind` — the agent runs below its target. `above_pin` — the agent runs above its target, and no rollback lowered that target, for example a fresh install of the newest release that joins a pinned environment. It is left there: nothing downgrades it automatically. `rollback_pending` — the agent runs above its target because a rollback lowered that target (changeAgentVersionPolicy with `rollback: true`), applied in Production once its approval request is approved and in any other environment as soon as an owner or admin makes it. The orchestrator downgrades the agent to its target once it is idle, audited as operation `rollback`; upgradeAgent to the target is the manual retry. `upgrade_required` — the running version or the target is below a version floor the api requires; `upgrade_required_reason` says which. The orchestrator moves an idle agent that reports the `native` deployment mode and is not `upgrade_paused` to `target_version` from three states only: `behind`, `rollback_pending`, and `upgrade_required` with `upgrade_required_reason` `agent_below_floor`, whose target is valid. It leaves an agent that is `current`, `above_pin`, or `upgrade_required` with `pin_below_floor`, whose pin must move first. An externally managed agent (`externally_managed`) is derived the same way, so it can be `behind` or `upgrade_required` too. Valid values are: `current`, `behind`, `above_pin`, `rollback_pending`, `upgrade_required`. Examples: `behind`.
`target_version`	string	No	The agent’s effective target: the version its environments’ policies derive, the strictest of them winning (the lowest pinned version, otherwise the newest release once its settle delay has passed). Derived per request, never stored. Absent when it cannot be derived. Examples: `5.1.3`.
The agent’s effective target: the version its environments’ policies derive, the strictest of them winning (the lowest pinned version, otherwise the newest release once its settle delay has passed). Derived per request, never stored. Absent when it cannot be derived. Examples: `5.1.3`.
`tenant_id`	string	Yes	Identifier of the owning organization.
Identifier of the owning organization.
`updated_at`	string	No	Timestamp the agent was last modified; returned by the detail endpoint only.
Timestamp the agent was last modified; returned by the detail endpoint only.
`upgrade_failure_reason`	string	No	The classified reason the agent’s last upgrade failed. Present while `upgrade_paused` is true. It is a code the agent reported, for example `upgrade_smoke_test_failed` or `upgrade_wrong_version`, or `ack_timeout` when the agent never acknowledged the upgrade. Examples: `upgrade_smoke_test_failed`.
The classified reason the agent’s last upgrade failed. Present while `upgrade_paused` is true. It is a code the agent reported, for example `upgrade_smoke_test_failed` or `upgrade_wrong_version`, or `ack_timeout` when the agent never acknowledged the upgrade. Examples: `upgrade_smoke_test_failed`.
`upgrade_paused`	boolean	No	True when the agent’s last upgrade failed, so automatic upgrades for it are paused and it keeps running its current binary. A manual upgradeAgent to its `target_version` is the retry: it clears the pause. A manual upgrade to any other version leaves it set.
True when the agent’s last upgrade failed, so automatic upgrades for it are paused and it keeps running its current binary. A manual upgradeAgent to its `target_version` is the retry: it clears the pause. A manual upgrade to any other version leaves it set.
`upgrade_required_reason`	string	No	Why the agent is `upgrade_required`. Present only when `target_state` is `upgrade_required`. `agent_below_floor` — the running version is below `floor_version`. `pin_below_floor` — `target_version` is a pin below `floor_version`, for example a floor raised after the pin was saved. The pin moves only by a promotion, never automatically. Valid values are: `agent_below_floor`, `pin_below_floor`. Examples: `pin_below_floor`.
Why the agent is `upgrade_required`. Present only when `target_state` is `upgrade_required`. `agent_below_floor` — the running version is below `floor_version`. `pin_below_floor` — `target_version` is a pin below `floor_version`, for example a floor raised after the pin was saved. The pin moves only by a promotion, never automatically. Valid values are: `agent_below_floor`, `pin_below_floor`. Examples: `pin_below_floor`.
`version`	string	No	Semantic version reported by the agent at handshake.
Semantic version reported by the agent at handshake.
`version_skew`	string	No	Whether the agent’s reported version is behind the newest published agent release. Derived per request, never stored. ‘unknown’ when the agent has never reported a version or the release list is unavailable. Valid values are: `up_to_date`, `behind`, `ahead`, `unknown`. Examples: `behind`.
Whether the agent’s reported version is behind the newest published agent release. Derived per request, never stored. ‘unknown’ when the agent has never reported a version or the release list is unavailable. Valid values are: `up_to_date`, `behind`, `ahead`, `unknown`. Examples: `behind`.

Agent Command Outcome

type: AgentCommandOutcome

The fate of the most recent command dispatched to this agent that is still worth showing an operator. Derived per request by joining the dispatch record to the agent’s terminal acknowledgement — never stored, so it cannot drift out of date. Absent when nothing was dispatched recently, when a terminal outcome has aged out, or when the agent predates the release that acknowledges commands (agent v4.1.0). An older agent reports nothing rather than being reported as unresponsive.

Property	Type	Required	Description
`command`	string	Yes	Which command this outcome belongs to, named without its `cmd.` frame prefix. Only `upgrade` currently has an operator-facing surface; every other command is recorded and returned, and nothing renders it. Examples: `upgrade`.
Which command this outcome belongs to, named without its `cmd.` frame prefix. Only `upgrade` currently has an operator-facing surface; every other command is recorded and returned, and nothing renders it. Examples: `upgrade`.
`dispatched_at`	string	Yes	When the command was dispatched. A command that was delivered and then went unanswered becomes `no_answer` after a deadline measured from this moment. A command still waiting for a disconnected agent stays `queued_offline` until it is delivered or expires — an agent that is switched off has not failed to answer.
When the command was dispatched. A command that was delivered and then went unanswered becomes `no_answer` after a deadline measured from this moment. A command still waiting for a disconnected agent stays `queued_offline` until it is delivered or expires — an agent that is switched off has not failed to answer.
`finished_at`	string	No	When the terminal acknowledgement was observed; absent while the command is in flight or queued.
When the terminal acknowledgement was observed; absent while the command is in flight or queued.
`id`	string	Yes	Correlation id of the dispatch — the same value the endpoint that dispatched the command returned.
Correlation id of the dispatch — the same value the endpoint that dispatched the command returned.
`message`	string	No	Diagnostic detail exactly as the agent reported it — for several failures this is a raw Go error string. Untranslated, agent-authored, and not curated for an operator audience: render localized copy from `state`, and treat this as supplementary detail rather than the primary explanation. Examples: `This agent already runs the newest release.`.
Diagnostic detail exactly as the agent reported it — for several failures this is a raw Go error string. Untranslated, agent-authored, and not curated for an operator audience: render localized copy from `state`, and treat this as supplementary detail rather than the primary explanation. Examples: `This agent already runs the newest release.`.
`reason`	string	No	Machine-readable code the agent reported with a terminal outcome, passed through unchanged. Deliberately not enumerated: the vocabulary is defined by the agent’s command handlers and grows with them. Read `state` to decide how to render; read this only to identify one specific case. Examples: `upgrade_not_needed`.
Machine-readable code the agent reported with a terminal outcome, passed through unchanged. Deliberately not enumerated: the vocabulary is defined by the agent’s command handlers and grows with them. Read `state` to decide how to render; read this only to identify one specific case. Examples: `upgrade_not_needed`.
`state`	string	Yes	`in_flight` — delivered to a connected agent, no acknowledgement yet, still within the command’s deadline. `queued_offline` — the agent was not connected, so the frame was persisted for delivery when it reconnects. `done` — the agent acknowledged success. `refused` — the agent declined by design. Nothing was changed and nothing is wrong; render it as a note, never as an error. `failed` — the agent attempted the command and it failed. `no_answer` — the deadline passed with no acknowledgement. This is what an agent that dies mid-command produces: the process that would have reported the failure no longer exists, so only the deadline reveals it. Valid values are: `in_flight`, `queued_offline`, `done`, `refused`, `failed`, `no_answer`. Examples: `refused`.
`in_flight` — delivered to a connected agent, no acknowledgement yet, still within the command’s deadline. `queued_offline` — the agent was not connected, so the frame was persisted for delivery when it reconnects. `done` — the agent acknowledged success. `refused` — the agent declined by design. Nothing was changed and nothing is wrong; render it as a note, never as an error. `failed` — the agent attempted the command and it failed. `no_answer` — the deadline passed with no acknowledgement. This is what an agent that dies mid-command produces: the process that would have reported the failure no longer exists, so only the deadline reveals it. Valid values are: `in_flight`, `queued_offline`, `done`, `refused`, `failed`, `no_answer`. Examples: `refused`.

Environment Slug

type: EnvironmentSlug

The slug of a DTAP environment.

Agent Lifecycle Status

type: AgentLifecycleStatus

Lifecycle status of an agent.

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

Upgrade Agent Request

type: UpgradeAgentRequest

The optional target of an agent upgrade. An empty body, or no body, means the newest published release.

Property	Type	Required	Description
`version`	string	No	The published, non-prerelease release to install. A version below the running one is refused with `downgrade_requires_rollback`, unless it is the agent’s effective target and the agent’s `target_state` is `rollback_pending`. Examples: `5.1.3`.
The published, non-prerelease release to install. A version below the running one is refused with `downgrade_requires_rollback`, unless it is the agent’s effective target and the agent’s `target_state` is `rollback_pending`. Examples: `5.1.3`.

Icpc Command Accepted

type: IcpcCommandAccepted

Confirmation that a command frame was QUEUED. It says nothing about whether the agent accepted, refused or completed the command; that outcome arrives as an ICPC event.

Property	Type	Required	Description
`agent_id`	string	Yes

`id`	string	Yes	Correlation id — matches the event frames this command produces.
Correlation id — matches the event frames this command produces.
`status`	string	Yes	`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`queued` means the frame went straight down a live connection. `queued_offline` means the agent was not connected and the frame was persisted for delivery when it reconnects — so a correlated outcome may be minutes away rather than seconds. Valid values are: `queued`, `queued_offline`.
`type`	string	Yes	Examples: `cmd.upgrade`.
Examples: `cmd.upgrade`.

Upgrade Agent Refusal

type: UpgradeAgentRefusal

Why an upgrade could not be attempted. Refusals are designed answers, not failures — each one means the upgrade was declined before anything on the agent was changed.

Property	Type	Required	Description
`message`	string	Yes	Human-readable explanation, safe to show an operator. Examples: `This agent runs in a container; upgrade its image instead.`.
Human-readable explanation, safe to show an operator. Examples: `This agent runs in a container; upgrade its image instead.`.
`reason`	string	Yes	Machine-readable refusal reason. `upgrade_externally_managed` — the agent’s platform owns its binary and would overwrite the change; `message` names what to update instead. `upgrade_agent_unreachable` — the agent is not currently connected, so the command could not be delivered. Retry when it reconnects. `upgrade_agent_busy` — the agent is connected but a run is in flight. Retry when it is idle. `upgrade_not_needed` — there is nothing to upgrade to, either because the agent already runs the target release or because the newest release could not be determined. `approval_required` — the target is above the version a pinned environment of the agent holds. That pin must move first, through changeAgentVersionPolicy: a change to Production applies once its approval request is approved, and a change to any other environment applies at once. `downgrade_requires_rollback` — the target is below the running version and is not a downgrade the agent is due. Only the effective target of an agent whose `target_state` is `rollback_pending` moves it down: an agent moves down only after a rollback of its environment’s pin. Valid values are: `upgrade_externally_managed`, `upgrade_agent_unreachable`, `upgrade_agent_busy`, `upgrade_not_needed`, `approval_required`, `downgrade_requires_rollback`. Examples: `upgrade_externally_managed`.
Machine-readable refusal reason. `upgrade_externally_managed` — the agent’s platform owns its binary and would overwrite the change; `message` names what to update instead. `upgrade_agent_unreachable` — the agent is not currently connected, so the command could not be delivered. Retry when it reconnects. `upgrade_agent_busy` — the agent is connected but a run is in flight. Retry when it is idle. `upgrade_not_needed` — there is nothing to upgrade to, either because the agent already runs the target release or because the newest release could not be determined. `approval_required` — the target is above the version a pinned environment of the agent holds. That pin must move first, through changeAgentVersionPolicy: a change to Production applies once its approval request is approved, and a change to any other environment applies at once. `downgrade_requires_rollback` — the target is below the running version and is not a downgrade the agent is due. Only the effective target of an agent whose `target_state` is `rollback_pending` moves it down: an agent moves down only after a rollback of its environment’s pin. Valid values are: `upgrade_externally_managed`, `upgrade_agent_unreachable`, `upgrade_agent_busy`, `upgrade_not_needed`, `approval_required`, `downgrade_requires_rollback`. Examples: `upgrade_externally_managed`.

Agent Status

type: AgentStatus

The polled status of an agent.

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`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.
`status`	AgentLifecycleStatus	Yes

Agent Rejection

type: AgentRejection

The payload for rejecting an agent.

Property	Type	Required	Description
`reason`	string	Yes	Reason for the rejection; recorded in the audit trail.
Reason for the rejection; recorded in the audit trail.

Agent Ref

type: AgentRef

A reference to an agent and its current status.

Property	Type	Required	Description
`agent_id`	string	Yes	Identifier of the agent.
Identifier of the agent.
`status`	AgentLifecycleStatus	Yes

Icpc Event List

type: IcpcEventList

Property	Type	Required	Description
`agent_id`	string	Yes

`count`	integer	Yes	Number of events in this response, after the limit is applied.
Number of events in this response, after the limit is applied.
`events`	IcpcEvent []	Yes

`total`	integer	Yes	Total events stored for this agent, ignoring the limit.
Total events stored for this agent, ignoring the limit.

Icpc Event

type: IcpcEvent

One ICPC frame observed from an agent that matched no handler.

Property	Type	Required	Description
`agent_id`	string	Yes

`id`	string	No	The frame’s correlation id, when it carried one. Matches the id returned by the command that caused it.
The frame’s correlation id, when it carried one. Matches the id returned by the command that caused it.
`observed_at`	string	Yes

`payload`	string	No	The frame’s raw payload, as received. Absent when `payload_withheld` is true. A caller who does not hold both `projects.update` and `sources.write` does not receive the payload of an `error` frame, nor of an `event.cmd_finished` frame unless the `command_type` it claims is one of `cmd.execute_job`, `cmd.execute_flow`, `cmd.stop_job`, `cmd.install_plugin`, `cmd.pull_config`, `cmd.import`, `cmd.deploy`, `cmd.advise`, `cmd.lint`, `cmd.validate`, `cmd.upgrade` or `cmd.render_sql`. So a `cmd.test_connection` answer, an answer with no or an unknown `command_type`, and every `error` frame are withheld: a connection test answers with the driver’s own text, which can name the connection’s login. The `command_type` read is the one the agent claims in the frame, not the one the api dispatched.
The frame’s raw payload, as received. Absent when `payload_withheld` is true. A caller who does not hold both `projects.update` and `sources.write` does not receive the payload of an `error` frame, nor of an `event.cmd_finished` frame unless the `command_type` it claims is one of `cmd.execute_job`, `cmd.execute_flow`, `cmd.stop_job`, `cmd.install_plugin`, `cmd.pull_config`, `cmd.import`, `cmd.deploy`, `cmd.advise`, `cmd.lint`, `cmd.validate`, `cmd.upgrade` or `cmd.render_sql`. So a `cmd.test_connection` answer, an answer with no or an unknown `command_type`, and every `error` frame are withheld: a connection test answers with the driver’s own text, which can name the connection’s login. The `command_type` read is the one the agent claims in the frame, not the one the api dispatched.
`payload_withheld`	boolean	No	True when the frame’s payload was withheld from this caller. Omitted otherwise, so a payload that is absent without this flag was not withheld. Examples: `true`.
True when the frame’s payload was withheld from this caller. Omitted otherwise, so a payload that is absent without this flag was not withheld. Examples: `true`.
`type`	string	Yes	Examples: `error`.
Examples: `error`.

Icpc Command Request

type: IcpcCommandRequest

A command frame to queue on an agent’s ICPC connection.

Property	Type	Required	Description
`id`	string	No	Correlation id for the command. The server assigns a UUID when omitted, and echoes it back so the caller can tie an event to this dispatch.
Correlation id for the command. The server assigns a UUID when omitted, and echoes it back so the caller can tie an event to this dispatch.
`payload`	object	No	Opaque command arguments. The api does not interpret this — the agent-side handler for `type` defines its shape.
Opaque command arguments. The api does not interpret this — the agent-side handler for `type` defines its shape.
`type`	string	Yes	The command frame type. Must be a `cmd.*` name the agent implements; anything else is rejected before dispatch. Examples: `cmd.upgrade`.
The command frame type. Must be a `cmd.*` name the agent implements; anything else is rejected before dispatch. Examples: `cmd.upgrade`.

Agent Approval

type: AgentApproval

The optional payload for approving an agent.

Property	Type	Required	Description
`reason`	string	No	Optional reason recorded in the audit trail.
Optional reason recorded in the audit trail.

Last updated on October 31, 2026

Docs

agent

GET /v1/agents

Parameters

Responses

Security

POST /v1/agents/{agent_id}/upgrade

Parameters

Request body

Responses

Security

GET /v1/agents/{agent_id}/status

Parameters

Responses

POST /v1/agents/{agent_id}/reject

Parameters

Request body (required)

Responses

Security

GET /v1/agents/{agent_id}/icpc-events

Parameters

Responses

Security

POST /v1/agents/{agent_id}/icpc-cmd

Parameters

Request body (required)

Responses

Security

POST /v1/agents/{agent_id}/approve

Parameters

Request body

Responses

Security

GET /v1/agents/{agent_id}

Parameters

Responses

Security

DELETE /v1/agents/{agent_id}

Parameters

Responses

Security

Schemas

Agent List

Agent

Agent Command Outcome

Environment Slug

Agent Lifecycle Status

Error

Upgrade Agent Request

Icpc Command Accepted

Upgrade Agent Refusal

Agent Status

Agent Rejection

Agent Ref

Icpc Event List

Icpc Event

Icpc Command Request

Agent Approval

On this page

GET `/v1/agents`

POST `/v1/agents/{agent_id}/upgrade`

GET `/v1/agents/{agent_id}/status`

POST `/v1/agents/{agent_id}/reject`

GET `/v1/agents/{agent_id}/icpc-events`

POST `/v1/agents/{agent_id}/icpc-cmd`

POST `/v1/agents/{agent_id}/approve`

GET `/v1/agents/{agent_id}`

DELETE `/v1/agents/{agent_id}`