Retrieve an approval.

GET

/approvals/{approval_id}

const url = 'https://shiftagent.example.com/approvals/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://shiftagent.example.com/approvals/example \
  --header 'Authorization: Bearer <token>'

Fetch an approval, including reason (the agent’s stated need), requested_items, and resolution state.

Authorizations

integrationKey

Parameters

Path Parameters

approval_id

required

string

/^apr_[A-Za-z0-9]+$/

Internal approval ID.

Responses

200

The approval.

application/json

A human-in-the-loop gate raised by the agent mid-run. Resolution requires a signed assertion minted with a per-tenant approver key (never the sk_int_ service key).

object

object

required

string

Allowed value: approval

required

string

/^apr_[A-Za-z0-9]+$/

tenant_id

required

string

/^tnt_[A-Za-z0-9]+$/

conversation_id

required

string

/^con_[A-Za-z0-9]+$/

message_id

required

The assistant message parked on this approval.

string

/^msg_[A-Za-z0-9]+$/

status

required

expired — expires_at passed unresolved; the parked run ended failed.

string

Allowed values: pending approved denied expired

reason

required

Agent-stated explanation of why approval is needed.

string

requested_items

required

What the agent needs (actions and/or secrets).

Array<object>

One thing the agent needs to proceed.

object

kind

required

action — permission to perform a described action; secret — a credential to be supplied under alias via the approve body’s secrets map.

string

Allowed values: action secret

description

required

Agent-stated need, human-readable.

string

alias

For secret items — the alias to vault the value under.

string

/^[A-Z][A-Z0-9_]{0,63}$/

expires_at

required

Resolution deadline; sticky sandboxes stay warm until then.

string format: date-time

resolved_by

Approver-key identity that resolved it (e.g. approver_key:apk_…); null while pending.

string | null

resolved_at

Resolution time; null while pending.

string | null format: date-time

created_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

updated_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

Example

{
  "object": "approval",
  "status": "pending",
  "requested_items": [
    {
      "kind": "action"
    }
  ]
}

401

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}

404

Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

not_found

Unknown resource

{
  "type": "https://shiftagent.example.com/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No tenant with external_id acme:tenant:999999.",
  "request_id": "req_01hzx8nf001"
}