Skip to content
UltimateTeam.ai Docs

List pending approvals

GET
/api/v1/approvals
curl --request GET \
  --url 'https://api.ultimateteam.ai/api/v1/approvals?limit=20&offset=0' \
  --header 'X-API-Key: <X-API-Key>'

Returns all actions awaiting human approval for the authenticated tenant, ordered by creation time.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
limit
Limit

Maximum number of approvals to return

integer
default: 20 >= 1 <= 100

Maximum number of approvals to return

offset
Offset

Number of approvals to skip

integer
0

Number of approvals to skip

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
ApprovalListResponse

Envelope response for the approval list endpoint.

Attributes: data: The approval list payload. meta: Standard response metadata.

object
data
required
ApprovalListData

Inner data payload for the approval list response.

Attributes: approvals: List of pending approval items. total: Total number of pending approvals.

object
approvals
Approvals
Array<object>
ApprovalItemSchema

A single pending approval in the queue.

Attributes: id: Unique identifier for this approval item. agent_role: The agent that requested the action. action_type: Machine-readable action identifier. description: Human-readable description of the proposed action. reasoning: Why the engine decided this needs approval. urgency: How time-sensitive this approval is. estimated_impact: Estimated business impact of the action. created_at: When this item was added to the queue. source: Origin queue (“decision” | “workflow_gate”). workflow_run_id: Workflow run UUID when source is workflow_gate.

object
action_type
required
Action Type
string
agent_role
required
Agent Role
string
approval_token
Any of:
string
created_at
required
Created At
string format: date-time
description
required
Description
string
estimated_impact
Estimated Impact
object
key
additional properties
Any of:
string
execution_plan
Any of:
ExecutionPlan

Structured pre-act plan generated before Level 2+ agent actions.

object
authority
Any of:
object
key
additional properties
any
debate
Any of:
DebateRecord
object
arguments
Arguments
Array<object>
DebateArgument
object
agent_role
required
Agent Role
string
argument
required
Argument
string
stance
required
Stance
string
task_id
required
Task Id
string
decision_id
required
Decision Id
string
error
Any of:
string
net_recommendation
Net Recommendation
string
default: escalate
Allowed values: proceed reconsider escalate
owner_kind
Owner Kind
string
default: decision
Allowed values: decision intention
status
Status
string
default: pending
Allowed values: pending complete blocked
synthesis
Synthesis
string
""
task_ids
Task Ids
object
key
additional properties
string
tenant_id
required
Tenant Id
string
triggered_by
required
Triggered By
string
overall_risk
required
Overall Risk
string
Allowed values: low medium high critical
preference_evidence
Preference Evidence
Array<object>
PreferenceEvidence
object
context_text
required
Context Text
string
id
required
Id
string
outcome
required
Outcome
string
Allowed values: approved rejected
similarity
required
Similarity
number
steps
required
Steps
Array<object>
ExecutionPlanStep

A single step in a pre-act execution plan.

object
action_type
required
Action Type
string
credit_cost
Credit Cost
integer
0
description
required
Description
string
reversible
required
Reversible
boolean
risk_level
Risk Level
string
default: low
Allowed values: low medium high critical
step_number
required
Step Number
integer
task_type
required
Task Type
string
total_credits
required
Total Credits
integer
total_steps
required
Total Steps
integer
id
required
Id
string
reasoning
Reasoning
string
""
source
Source
string
default: decision
urgency
Urgency
string
default: normal
workflow_run_id
Any of:
string
total
Total
integer
0
meta
ResponseMeta

Standard metadata included in every API response.

Attributes: request_id: Unique identifier for this request. timestamp: When the response was generated.

object
request_id
Request Id

Unique identifier for this request

string
timestamp
Timestamp

When the response was generated

string format: date-time
Example
{
  "data": {
    "approvals": [
      {
        "execution_plan": {
          "debate": {
            "net_recommendation": "proceed",
            "owner_kind": "decision",
            "status": "pending",
            "synthesis": ""
          },
          "overall_risk": "low",
          "preference_evidence": [
            {
              "outcome": "approved"
            }
          ],
          "steps": [
            {
              "credit_cost": 0,
              "risk_level": "low"
            }
          ]
        },
        "reasoning": "",
        "source": "decision",
        "urgency": "normal"
      }
    ],
    "total": 0
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}