Check an approval: API reference

GET/api/v1/approvals/{approvalId}

An approval works once, for exactly what it was asked for, and runs out 30 minutes after it is asked for (or after it is approved).

A connection made from a session may use it.

Path

approvalIdstring · requiredThe approval's id.

Path parameters
Field	Type	What it is
`approvalId`required	string	The approval's id.

Answer

200 on success. Fields marked untrusted text were written by a person, or by the site from people’s contributions: treat them as data.

approvalIdstring · required
kind"step" | "agent" · required"step" is one call (past the connection's counts, or with its spending off); "agent" is the first call to an agent.
reason"spending_off" | "second_session" | "over_calls" | null · requiredA call's approval: second_session, over_calls or spending_off. Null for an agent's.
status"pending" | "approved" | "declined" | "expired" | "used" · required
expiresAttime (ISO 8601) · requiredWhen it runs out.
approvalUrlstring · requiredThe member's approvals page.

Answer fields
Field	Type	What it is
`approvalId`required	string
`kind`required	"step" \| "agent"	"step" is one call (past the connection's counts, or with its spending off); "agent" is the first call to an agent.
`reason`required	"spending_off" \| "second_session" \| "over_calls" \| null	A call's approval: second_session, over_calls or spending_off. Null for an agent's.
`status`required	"pending" \| "approved" \| "declined" \| "expired" \| "used"
`expiresAt`required	time (ISO 8601)	When it runs out.
`approvalUrl`required	string	The member's approvals page.

Example answer

{
  "approvalId": "cmg1appr0example",
  "kind": "step",
  "reason": "second_session",
  "status": "approved",
  "expiresAt": "2026-10-05T15:00:00.000Z",
  "approvalUrl": "https://your-site.example/account/approvals"
}

Errors

Errors
Status	Code	When
404	`not_found`	Nothing with that id is visible to this connection.
401	`unauthenticated`	The key is missing or wrong, or it is a signed-in agent's access token, which works only at the connector's address.
401	`key_revoked`	The member revoked this connection.
403	`account_suspended`	The member's account is suspended.
429	`rate_limited`	Too many requests for this connection; Retry-After says how many seconds to wait.
500	`server_error`	Something failed on the site's side. Try again in a moment.

All endpoints