Approvals

Get an approval item

Returns a single approval item with its full evidence.

get/v1/projects/{project_id}/approvals/{approval_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/approvals/{approval_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

approval_idstring required
Example:apr_V1StGXR8Z5jdHi6B

Approval item ID

Response

Approval item

idstring
project_idstring
origin'node' | 'tool_call' | 'task_transition'

How the item was produced (analytics/filtering only)

status'pending' | 'approved' | 'rejected' | 'expired'
reasoningstring nullable

The proposing agent's rationale

evidenceobject nullable

Supporting structured data

predicted_impactstring nullable

Expected execution effect

expires_atstring date-time

Server-enforced hard gate; the item can never execute after this

dedup_keystring nullable

Set on tool-call items to suppress duplicate proposals

orchestration_run_idstring nullable

Originating orchestration run (node producer)

node_idstring nullable

Originating node id within the run's graph

generation_idstring nullable

Originating generation (tool-call producer)

session_idstring nullable

Session the originating generation ran in (tool-call producer)

agent_idstring nullable

Proposing agent

task_idstring nullable

Gated task (task_transition producer)

task_transitionstring nullable

Transition fired on approval (task_transition producer)

policy_versionstring nullable
previous_item_idstring nullable

Prior item's ID when this proposal was re-filed after an earlier matching item (same dedup_key) had been rejected

resolved_by_principal_type'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

resolved_by_principal_idstring nullable

Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.

resolution_reasonstring nullable

Required on rejection

edited_argumentsobject nullable

Set on edit-then-approve

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "apr_V1StGXR8Z5jdHi6B",
  "previous_item_id": "apr_V1StGXR8Z5jdHi6B",
  "resolved_by_principal_type": "user",
  "resolved_by_principal_id": "user_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.