Skip to content
shiftagent Integration API

List approvals.

GET
/approvals
 
curl --request GET \
  --url 'https://shiftagent.example.com/approvals?limit=20&status=pending' \
  --header 'Authorization: Bearer <token>'

Lists HITL approvals across the key’s subtree, newest first. Filter by ?tenant_id=, ?user_id=, ?conversation_id=, and/or ?status= (a pending-approvals inbox is ?status=pending&tenant_id=…). Serves hosts that poll instead of (or in addition to) consuming approval_required stream events.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 20 >= 1 <= 100

Page size (1–100).

starting_after
string

Cursor: return items after this object ID (forward pagination). Use the id of the last item of the previous page.

ending_before
string

Cursor: return items before this object ID (backward pagination). Mutually exclusive with starting_after.

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

Restrict to one tenant.

user_id
string
/^usr_[A-Za-z0-9]+$/

Restrict to conversations owned by one user.

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

Restrict to one conversation.

status
string
Allowed values: pending approved denied expired

Filter by approval status.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A page of approvals.

Media type application/json
object
object
required

Envelope discriminator.

string
Allowed value: list
data
required

The page of items.

Array
has_more
required

Whether more items exist beyond this page.

boolean
next_cursor

Opaque cursor for the next page (pass as starting_after). Null when has_more is false.

string | null
data
required
Array<object>

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
id
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": "list",
  "data": [
    {
      "object": "approval",
      "status": "pending",
      "requested_items": [
        {
          "kind": "action"
        }
      ]
    }
  ]
}

400

Section titled “400 ”

Bad request — malformed body/parameters or an invalid parameter combination (e.g. neither or both of user_id/tenant_id on listConversations, or both pagination cursors).

Media type 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
Example bad_request

Invalid parameter combination

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Invalid request",
  "status": 400,
  "detail": "Exactly one of user_id or tenant_id is required.",
  "request_id": "req_01hzx8bad001"
}

401

Section titled “401 ”

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

Media type 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
Example 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"
}