Intents and Governance API
Intents describe a proposed action before execution. Simulation and submission accept operator-scoped Bearer authentication and require an X-Passport-Token header. Agent-bearing authentication is also accepted. Approval and rejection require a non-agent principal.
Simulate
POST /v1/intents/simulate
curl -X POST https://api.getstack.run/v1/intents/simulate \
-H "Authorization: Bearer $STACK_TOKEN" -H "X-Passport-Token: $STACK_PASSPORT" \
-H "Content-Type: application/json" \
-d '{"intent":{"type":"intent_claim","intent_type":"http_call","agent_id":"agt_123","named_intent":"stripe.create_refund","target":"stripe","action":"POST /v1/refunds","parameters":{"url":"https://api.stripe.com/v1/refunds","method":"POST","body":{"charge":"ch_123","amount":500}},"estimated_cost":{"wallet_cents":0,"tokens":null,"gas_gwei":null},"accountability":"enforced","reason":"Refund the duplicate charge","requires":[],"user_subject":null,"mission_ref":null,"submitted_at":1787270400000}}'The response includes allowed, denial reasons, predicted detector signals, simulated cost, diagnostics, and an optional signed simulation claim.
Submit and inspect
- POST /v1/intents/submit - create a pending approval. X-Passport-Token is required.
- GET /v1/intents/:id - read one approval. Cross-operator IDs return 404.
- GET /v1/intents/pending - list pending approvals with page and limit.
Submission counts as one metered action. Simulation and decisions do not. A submitted approval expires and can be consumed only for the approved request shape.
Approve or reject
- POST /v1/intents/:id/approve
- POST /v1/intents/:id/reject
Agent JWTs and Passport-authenticated agent contexts receive 403 on both decision routes. Use the Console, an operator API key, or a non-agent OAuth session. Do not give an agent instructions to approve its own request.
Rejection schedules revocation of the associated Passport. This hook runs asynchronously. A hook failure does not change the recorded rejection. Set block_future to also block the agent from future Passport issuance.
Bearer governance step-up
Other scope-expanding Bearer actions can return 403 GOVERNANCE_APPROVAL_REQUIRED. Open the returned dashboard URL, let a human approve the payload, then retry the exact request with X-Governance-Approval. The approval is single-use, payload-bound, and expires after 15 minutes.