Docs
agent-versions
The organization's agent version policy per DTAP environment: follow the newest release, or hold a pinned version that moves by promotion.
Amfelt REST API · v1.13.0
· https://api.amfelt.com
GET
/v1/orgs/{slug}/agent-version-policies
List the organization's agent version policies.
Returns one agent version policy per DTAP environment of the organization. A policy is set once per environment for the whole organization: every project’s environment of that type follows it. An agent serving several environments follows the strictest of their policies — the lowest pinned version wins — and the target each agent derives from them is computed at read time, never stored.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | Yes | string | Slug of the organization. |
Slug of the organization. | ||||
Responses
200
The organization's agent version policies.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
data | AgentVersionPolicy [] | 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. | |||
Security
bearer_jwt
GET
/v1/orgs/{slug}/agent-version-policies/{environment_id}/evidence
Read the evidence for promoting one environment's pin.
Returns the evidence a promotion of this environment’s pin toversion would carry: the recorded runs of that version in lower environments. The promotion dialog reads it before its first submit; changeAgentVersionPolicy attaches the same evidence to its answer. Zero runs is valid evidence, shown as such.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | Yes | string | Slug of the organization. |
Slug of the organization. | ||||
environment_id | path | Yes | string | The DTAP environment slug whose pin would move. |
The DTAP environment slug whose pin would move. | ||||
version | query | Yes | string | The version a promotion would pin. |
The version a promotion would pin. | ||||
Responses
200
The recorded runs of the version in lower environments.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
environments | EnvironmentSlug [] | Yes | The DTAP environment slugs that ran the version, in promotion order. Examples: ["test","acceptance"]. |
The DTAP environment slugs that ran the version, in promotion order. Examples: ["test","acceptance"]. | |||
first_at | [string null] | Yes | When the first of those runs started; null when there are none. |
When the first of those runs started; null when there are none. | |||
last_at | [string null] | Yes | When the last of those runs started; null when there are none. |
When the last of those runs started; null when there are none. | |||
runs | integer | Yes | Successful runs the version executed in lower environments. Examples: 12. |
Successful runs the version executed in lower environments. Examples: 12. | |||
400
The request was malformed or failed validation.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
401
The request lacks valid credentials.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
403
The caller is authenticated but not permitted to perform the request.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
404
The specified resource was not found.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
Security
bearer_jwt
POST
/v1/orgs/{slug}/agent-version-policies/{environment_id}/changes
Change one environment's agent version policy.
Requests a change to one environment’s agent version policy: a pin move (a promotion to a newer version, or a rollback to an earlier one withrollback: true), a switch between follow_latest and pinned, or a new settle_delay_minutes.
A change to Production needs approval, whatever it changes, the settle delay included: the response is 202 with an approval request of kind agent_version_policy_change, and the policy changes only when that request is approved. A change to any other environment needs no approval: it is applied at once and the response is 200 with the applied policy. An environment has at most one pending request: a change while one is pending is refused with approval_already_pending.
A promotion (a change that moves pinned_version up) carries the evidence of the runs that version executed in lower environments: on a 200 in the policy’s evidence, on a 202 in the approval request’s payload.evidence. Evidence is shown, not required: a promotion with no recorded runs is refused with evidence_unconfirmed until it is resent with confirm_without_evidence: true. A rollback needs no evidence.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | Yes | string | Slug of the organization. |
Slug of the organization. | ||||
environment_id | path | Yes | string | The DTAP environment slug whose policy changes. |
The DTAP environment slug whose policy changes. | ||||
Request body (required)
application/json
| Property | Type | Required | Description |
|---|---|---|---|
confirm_without_evidence | boolean | No | Confirms a promotion to a version with no recorded runs in lower environments. Without it such a promotion is refused with evidence_unconfirmed. |
Confirms a promotion to a version with no recorded runs in lower environments. Without it such a promotion is refused with evidence_unconfirmed. | |||
mode | AgentVersionPolicyMode | Yes | |
pinned_version | string | No | The version to pin. Required when mode is pinned, and must be absent when it is follow_latest. Examples: 5.2.0. |
The version to pin. Required when mode is pinned, and must be absent when it is follow_latest. Examples: 5.2.0. | |||
reason | string | No | Why the change is made. When the change needs approval, it is carried on the approval request’s payload and shown to the approver. It is not stored for a change that applies at once. Examples: Ran clean in Acceptance for two weeks.. |
Why the change is made. When the change needs approval, it is carried on the approval request’s payload and shown to the approver. It is not stored for a change that applies at once. Examples: Ran clean in Acceptance for two weeks.. | |||
rollback | boolean | No | True when the change is a rollback: it pins a pinned_version lower than the environment’s current target, which is its pin when mode is pinned and otherwise the newest release past its settle delay. The flag must match the change: rollback: true on a change that pins no lower version is refused with rollback_not_lower, and a lower pinned_version without it is refused with rollback_unconfirmed. A rollback needs no evidence, because the environment ran that version before. |
True when the change is a rollback: it pins a pinned_version lower than the environment’s current target, which is its pin when mode is pinned and otherwise the newest release past its settle delay. The flag must match the change: rollback: true on a change that pins no lower version is refused with rollback_not_lower, and a lower pinned_version without it is refused with rollback_unconfirmed. A rollback needs no evidence, because the environment ran that version before. | |||
settle_delay_minutes | integer | No | Minutes after a release is published before this environment’s follow_latest agents act on it. Absent keeps the current delay. A change to it follows the same approval rule as any other change to this environment’s policy. Examples: 60. |
Minutes after a release is published before this environment’s follow_latest agents act on it. Absent keeps the current delay. A change to it follows the same approval rule as any other change to this environment’s policy. Examples: 60. | |||
Responses
200
The change needed no approval and was applied.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
environment_id | EnvironmentSlug | Yes | |
evidence | AgentVersionEvidence | No | |
mode | AgentVersionPolicyMode | Yes | |
pinned_version | [string null] | Yes | The version agents of this environment hold. Set when mode is pinned, null when it is follow_latest. Examples: 5.1.3. |
The version agents of this environment hold. Set when mode is pinned, null when it is follow_latest. Examples: 5.1.3. | |||
settle_delay_minutes | integer | Yes | Minutes after a release is published before follow_latest agents act on it. Examples: 60. |
Minutes after a release is published before follow_latest agents act on it. Examples: 60. | |||
updated_at | string | Yes | When the policy last changed. |
When the policy last changed. | |||
updated_by | string | Yes | Identifier of the account that last changed the policy, or system when the platform set it. Examples: system. |
Identifier of the account that last changed the policy, or system when the platform set it. Examples: system. | |||
202
The change needs approval. The body is the pending approval request; the policy is unchanged until it is approved.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
decided_at | [string null] | No | When the request was approved or declined; null otherwise. |
When the request was approved or declined; null otherwise. | |||
decided_by | [string null] | No | Identifier of the account that approved or declined the request; null while it is pending or once it expired. |
Identifier of the account that approved or declined the request; null while it is pending or once it expired. | |||
expires_at | string | Yes | When a still-pending request becomes expired. |
When a still-pending request becomes expired. | |||
id | string | Yes | Approval request identifier. |
Approval request identifier. | |||
kind | string | Yes | What is being approved. An open vocabulary, so a new kind needs no contract change. Examples: agent_version_policy_change. |
What is being approved. An open vocabulary, so a new kind needs no contract change. Examples: agent_version_policy_change. | |||
payload | object | Yes | The kind-specific details of the request. |
The kind-specific details of the request. | |||
requested_at | string | Yes | When the request was made. |
When the request was made. | |||
requested_by | string | Yes | Identifier of the account that made the request. |
Identifier of the account that made the request. | |||
self_approved | boolean | Yes | True when the requester approved their own request, which is allowed only in an organization with exactly one owner or admin. |
True when the requester approved their own request, which is allowed only in an organization with exactly one owner or admin. | |||
state | ApprovalRequestState | 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 change was refused; the policy is unchanged.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
evidence | AgentVersionEvidence | No | |
message | string | Yes | Human-readable explanation, safe to show an operator. Examples: Pin 5.0.2 is below the version floor 5.1.0 that <feature> needs; pin 5.1.0 or later.. |
Human-readable explanation, safe to show an operator. Examples: Pin 5.0.2 is below the version floor 5.1.0 that <feature> needs; pin 5.1.0 or later.. | |||
reason | string | Yes | Machine-readable refusal reason. pin_below_floor — pinned_version is below a version floor the api requires; message names the floor and the feature it gates. evidence_unconfirmed — the promotion’s version has no recorded runs in lower environments; resend with confirm_without_evidence: true to proceed. approval_already_pending — this environment’s policy already has a pending approval request; it must be approved, declined or expire before another change is requested. rollback_not_lower — the change says rollback: true but pins no version lower than the environment’s current target. The flag and the change disagree, so nothing is applied: resend without rollback, or with a lower pinned_version. rollback_unconfirmed — the change pins a version lower than the environment’s current target without rollback: true; resend with rollback: true to roll back. Valid values are: pin_below_floor, evidence_unconfirmed, approval_already_pending, rollback_not_lower, rollback_unconfirmed. Examples: pin_below_floor. |
Machine-readable refusal reason. pin_below_floor — pinned_version is below a version floor the api requires; message names the floor and the feature it gates. evidence_unconfirmed — the promotion’s version has no recorded runs in lower environments; resend with confirm_without_evidence: true to proceed. approval_already_pending — this environment’s policy already has a pending approval request; it must be approved, declined or expire before another change is requested. rollback_not_lower — the change says rollback: true but pins no version lower than the environment’s current target. The flag and the change disagree, so nothing is applied: resend without rollback, or with a lower pinned_version. rollback_unconfirmed — the change pins a version lower than the environment’s current target without rollback: true; resend with rollback: true to roll back. Valid values are: pin_below_floor, evidence_unconfirmed, approval_already_pending, rollback_not_lower, rollback_unconfirmed. Examples: pin_below_floor. | |||
422
The request was well-formed but failed semantic 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. | |||
Security
bearer_jwt
Schemas
Agent Version Policy List
type: AgentVersionPolicyList
The organization’s agent version policies, one per DTAP environment.
| Property | Type | Required | Description |
|---|---|---|---|
data | AgentVersionPolicy [] | Yes | |
Agent Version Policy
type: AgentVersionPolicy
The agent version policy of one DTAP environment, shared by every project’s environment of that type in the organization.
| Property | Type | Required | Description |
|---|---|---|---|
environment_id | EnvironmentSlug | Yes | |
evidence | AgentVersionEvidence | No | |
mode | AgentVersionPolicyMode | Yes | |
pinned_version | [string null] | Yes | The version agents of this environment hold. Set when mode is pinned, null when it is follow_latest. Examples: 5.1.3. |
The version agents of this environment hold. Set when mode is pinned, null when it is follow_latest. Examples: 5.1.3. | |||
settle_delay_minutes | integer | Yes | Minutes after a release is published before follow_latest agents act on it. Examples: 60. |
Minutes after a release is published before follow_latest agents act on it. Examples: 60. | |||
updated_at | string | Yes | When the policy last changed. |
When the policy last changed. | |||
updated_by | string | Yes | Identifier of the account that last changed the policy, or system when the platform set it. Examples: system. |
Identifier of the account that last changed the policy, or system when the platform set it. Examples: system. | |||
Environment Slug
type: EnvironmentSlug
The slug of a DTAP environment.
Agent Version Evidence
type: AgentVersionEvidence
The recorded runs of the promoted version in lower environments, which the approver weighs. Zero runs is valid evidence, shown as such.
| Property | Type | Required | Description |
|---|---|---|---|
environments | EnvironmentSlug [] | Yes | The DTAP environment slugs that ran the version, in promotion order. Examples: ["test","acceptance"]. |
The DTAP environment slugs that ran the version, in promotion order. Examples: ["test","acceptance"]. | |||
first_at | [string null] | Yes | When the first of those runs started; null when there are none. |
When the first of those runs started; null when there are none. | |||
last_at | [string null] | Yes | When the last of those runs started; null when there are none. |
When the last of those runs started; null when there are none. | |||
runs | integer | Yes | Successful runs the version executed in lower environments. Examples: 12. |
Successful runs the version executed in lower environments. Examples: 12. | |||
Agent Version Policy Mode
type: AgentVersionPolicyMode
How an environment’s agents choose their version. follow_latest follows the newest published, non-prerelease release once its settle delay has passed. pinned holds pinned_version until a promotion or rollback moves it.
Error
type: Error
The standard error envelope returned by every non-2xx response.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
Agent Version Policy Change
type: AgentVersionPolicyChange
A requested change to one environment’s agent version policy.
| Property | Type | Required | Description |
|---|---|---|---|
confirm_without_evidence | boolean | No | Confirms a promotion to a version with no recorded runs in lower environments. Without it such a promotion is refused with evidence_unconfirmed. |
Confirms a promotion to a version with no recorded runs in lower environments. Without it such a promotion is refused with evidence_unconfirmed. | |||
mode | AgentVersionPolicyMode | Yes | |
pinned_version | string | No | The version to pin. Required when mode is pinned, and must be absent when it is follow_latest. Examples: 5.2.0. |
The version to pin. Required when mode is pinned, and must be absent when it is follow_latest. Examples: 5.2.0. | |||
reason | string | No | Why the change is made. When the change needs approval, it is carried on the approval request’s payload and shown to the approver. It is not stored for a change that applies at once. Examples: Ran clean in Acceptance for two weeks.. |
Why the change is made. When the change needs approval, it is carried on the approval request’s payload and shown to the approver. It is not stored for a change that applies at once. Examples: Ran clean in Acceptance for two weeks.. | |||
rollback | boolean | No | True when the change is a rollback: it pins a pinned_version lower than the environment’s current target, which is its pin when mode is pinned and otherwise the newest release past its settle delay. The flag must match the change: rollback: true on a change that pins no lower version is refused with rollback_not_lower, and a lower pinned_version without it is refused with rollback_unconfirmed. A rollback needs no evidence, because the environment ran that version before. |
True when the change is a rollback: it pins a pinned_version lower than the environment’s current target, which is its pin when mode is pinned and otherwise the newest release past its settle delay. The flag must match the change: rollback: true on a change that pins no lower version is refused with rollback_not_lower, and a lower pinned_version without it is refused with rollback_unconfirmed. A rollback needs no evidence, because the environment ran that version before. | |||
settle_delay_minutes | integer | No | Minutes after a release is published before this environment’s follow_latest agents act on it. Absent keeps the current delay. A change to it follows the same approval rule as any other change to this environment’s policy. Examples: 60. |
Minutes after a release is published before this environment’s follow_latest agents act on it. Absent keeps the current delay. A change to it follows the same approval rule as any other change to this environment’s policy. Examples: 60. | |||
Approval Request
type: ApprovalRequest
A change waiting for a second person. The resource is generic: kind names what is approved, and payload carries that kind’s details. For kind agent_version_policy_change the payload holds environment_id, mode, pinned_version, settle_delay_minutes, reason, rollback, and, for a promotion, evidence (an AgentVersionEvidence).
| Property | Type | Required | Description |
|---|---|---|---|
decided_at | [string null] | No | When the request was approved or declined; null otherwise. |
When the request was approved or declined; null otherwise. | |||
decided_by | [string null] | No | Identifier of the account that approved or declined the request; null while it is pending or once it expired. |
Identifier of the account that approved or declined the request; null while it is pending or once it expired. | |||
expires_at | string | Yes | When a still-pending request becomes expired. |
When a still-pending request becomes expired. | |||
id | string | Yes | Approval request identifier. |
Approval request identifier. | |||
kind | string | Yes | What is being approved. An open vocabulary, so a new kind needs no contract change. Examples: agent_version_policy_change. |
What is being approved. An open vocabulary, so a new kind needs no contract change. Examples: agent_version_policy_change. | |||
payload | object | Yes | The kind-specific details of the request. |
The kind-specific details of the request. | |||
requested_at | string | Yes | When the request was made. |
When the request was made. | |||
requested_by | string | Yes | Identifier of the account that made the request. |
Identifier of the account that made the request. | |||
self_approved | boolean | Yes | True when the requester approved their own request, which is allowed only in an organization with exactly one owner or admin. |
True when the requester approved their own request, which is allowed only in an organization with exactly one owner or admin. | |||
state | ApprovalRequestState | Yes | |
Approval Request State
type: ApprovalRequestState
Where an approval request stands. Only pending can change; the other three are final.
Agent Version Policy Change Refusal
type: AgentVersionPolicyChangeRefusal
Why a policy change was refused. Like the upgrade refusals, each one is a designed answer: nothing was changed.
| Property | Type | Required | Description |
|---|---|---|---|
evidence | AgentVersionEvidence | No | |
message | string | Yes | Human-readable explanation, safe to show an operator. Examples: Pin 5.0.2 is below the version floor 5.1.0 that <feature> needs; pin 5.1.0 or later.. |
Human-readable explanation, safe to show an operator. Examples: Pin 5.0.2 is below the version floor 5.1.0 that <feature> needs; pin 5.1.0 or later.. | |||
reason | string | Yes | Machine-readable refusal reason. pin_below_floor — pinned_version is below a version floor the api requires; message names the floor and the feature it gates. evidence_unconfirmed — the promotion’s version has no recorded runs in lower environments; resend with confirm_without_evidence: true to proceed. approval_already_pending — this environment’s policy already has a pending approval request; it must be approved, declined or expire before another change is requested. rollback_not_lower — the change says rollback: true but pins no version lower than the environment’s current target. The flag and the change disagree, so nothing is applied: resend without rollback, or with a lower pinned_version. rollback_unconfirmed — the change pins a version lower than the environment’s current target without rollback: true; resend with rollback: true to roll back. Valid values are: pin_below_floor, evidence_unconfirmed, approval_already_pending, rollback_not_lower, rollback_unconfirmed. Examples: pin_below_floor. |
Machine-readable refusal reason. pin_below_floor — pinned_version is below a version floor the api requires; message names the floor and the feature it gates. evidence_unconfirmed — the promotion’s version has no recorded runs in lower environments; resend with confirm_without_evidence: true to proceed. approval_already_pending — this environment’s policy already has a pending approval request; it must be approved, declined or expire before another change is requested. rollback_not_lower — the change says rollback: true but pins no version lower than the environment’s current target. The flag and the change disagree, so nothing is applied: resend without rollback, or with a lower pinned_version. rollback_unconfirmed — the change pins a version lower than the environment’s current target without rollback: true; resend with rollback: true to roll back. Valid values are: pin_below_floor, evidence_unconfirmed, approval_already_pending, rollback_not_lower, rollback_unconfirmed. Examples: pin_below_floor. | |||
Last updated on October 31, 2026