approvals

Generic approval requests: a change that needs a second person waits here until it is approved, declined, or expires.

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

GET `/v1/approval-requests`

List approval requests.

Returns a page of the organization’s approval requests, newest first, optionally filtered by state and by kind. Approval requests are generic: kind names what is being approved and payload carries its details, so agent version policy changes and other promotions share this resource.

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.
`state`	query	No	ApprovalRequestState	Only requests in this state.
Only requests in this state.
`kind`	query	No	string	Only requests of this kind, for example `agent_version_policy_change`.
Only requests of this kind, for example `agent_version_policy_change`.
`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 approval requests.

application/json

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

400 The request was malformed or failed validation.

application/json

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

401 The request lacks valid credentials.

application/json

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

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

application/json

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

Security

bearer_jwt

POST `/v1/approval-requests/{id}/decline`

Decline an approval request.

Declines a pending request. Nothing it asks for is applied.

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.
`id`	path	Yes	string	Identifier of the approval request.
Identifier of the approval request.

Responses

200 The declined request.

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

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 decline was refused; the request is unchanged.

application/json

Property	Type	Required	Description
`message`	string	Yes	Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
`reason`	string	Yes	Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.
Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.

Security

bearer_jwt

POST `/v1/approval-requests/{id}/approve`

Approve an approval request.

Approves a pending request and applies what it asks for. The approver’s authority is checked when they approve, not when the request was made, so an approver who has since left the organization or lost the role is refused with 403. The approver must be a second person. A requester approving their own request is refused with approval_same_actor, unless the organization has exactly one owner or admin: then the approval is accepted and recorded with self_approved: true.

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.
`id`	path	Yes	string	Identifier of the approval request.
Identifier of the approval request.

Responses

200 The approved request.

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

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 approval was refused; the request is unchanged.

application/json

Property	Type	Required	Description
`message`	string	Yes	Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
`reason`	string	Yes	Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.
Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.

Security

bearer_jwt

GET `/v1/approval-requests/{id}`

Get an approval request.

Returns one of the organization’s approval requests.

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.
`id`	path	Yes	string	Identifier of the approval request.
Identifier of the approval request.

Responses

200 The approval request.

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

401 The request lacks valid credentials.

application/json

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

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

application/json

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

404 The specified resource was not found.

application/json

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

Security

bearer_jwt

Schemas

Approval Request List

type: ApprovalRequestList

A page of approval requests.

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

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.

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

Approval Decision Refusal

type: ApprovalDecisionRefusal

Why an approval or a decline was refused. Nothing was changed.

Property	Type	Required	Description
`message`	string	Yes	Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
Human-readable explanation, safe to show an operator. Examples: `A second owner or admin must approve this request.`.
`reason`	string	Yes	Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.
Machine-readable refusal reason. `approval_same_actor` — the approver is the requester, and the organization has more than one owner or admin, so a second person must approve. `approval_not_pending` — the request is already approved, declined or expired. Valid values are: `approval_same_actor`, `approval_not_pending`. Examples: `approval_same_actor`.

Last updated on October 31, 2026

Docs

approvals

GET `/v1/approval-requests`

Parameters

Responses

Security

POST `/v1/approval-requests/{id}/decline`

Parameters

Responses

Security

POST `/v1/approval-requests/{id}/approve`

Parameters

Responses

Security

GET `/v1/approval-requests/{id}`

Parameters

Responses

Security

Schemas

Approval Request List

Approval Request

Approval Request State

Error

Approval Decision Refusal

On this page

Docs

approvals

GET /v1/approval-requests

Parameters

Responses

Security

POST /v1/approval-requests/{id}/decline

Parameters

Responses

Security

POST /v1/approval-requests/{id}/approve

Parameters

Responses

Security

GET /v1/approval-requests/{id}

Parameters

Responses

Security

Schemas

Approval Request List

Approval Request

Approval Request State

Error

Approval Decision Refusal

On this page

GET `/v1/approval-requests`

POST `/v1/approval-requests/{id}/decline`

POST `/v1/approval-requests/{id}/approve`

GET `/v1/approval-requests/{id}`