Skip to content

api reference

Intended Documentation

API Reference

The Intended runtime API — submit intents for an authority decision, manage authority policies, and pull the tamper-evident audit chain. Every route is fail-closed and tenant-scoped.

intermediate4 min readimplemented

API Reference#

The Intended API is the runtime that decides whether a proposed action is allowed to run, mints a single-use proof when it is, and records every step in a tamper-evident audit chain. There is no separate "decision" service and "logging" service to wire together — one request to POST /intent runs the full loop and returns the decision, the signed token, the execution outcome, and the audit head in a single response.

Every endpoint shares three guarantees, enforced in code rather than convention:

  • Fail-closed. If the runtime cannot reach a clear decision, it denies. A request that errors anywhere in the authority loop returns 500 AUTHORITY_LOOP_FAILED, never a silent allow.
  • Tenant-scoped. Your credential resolves to exactly one tenant. Routes that also carry a tenantId in the body or path reject a mismatch with 403 TENANT_MISMATCH — a hard cross-tenant isolation boundary.
  • Audited. State-changing operations append SHA-256 hash-chained audit entries as a side effect. You do not opt in.
The runtime request path
An API request authenticates at the gate, runs the authority loop to produce APPROVED, ESCALATED, or DENIED, mints an Ed25519 token only on APPROVED, and appends to the per-tenant SHA-256 audit chain throughout.

One POST /intent call carries the request through the gate, the authority loop, token issuance, execution, and the audit chain.

Base URL and versioning#

https://api.intended.so

A leading /v1 is accepted and stripped before routing, so /v1/intent and /intent reach the same handler. The paths in these pages omit the prefix.

The endpoints#

PageEndpointsWhat it does
Authentication—Credential types, the fail-closed gate, headers, scopes, rate limits, and the exact auth errors.
IntentsPOST /intent, GET /intents, GET /intents/:id, POST /intent/simulateThe core endpoint: submit an IntentRequest, get APPROVED / ESCALATED / DENIED plus a signed decision token.
PoliciesPOST /authority/evaluate, /authority/policies/*, /policy/* lifecycleEvaluate against authority policy, and draft, review, deploy, and roll back policy.
Audit/tenants/:t/audit, chain verification, evidence bundles, admin exportsQuery the hash chain, verify its integrity, and export signed evidence.

Warning

Two decision vocabularies exist and they are not interchangeable. POST /intent (the runtime loop) returns the legacy enum APPROVED / ESCALATED / DENIED. POST /authority/evaluate (the modern policy engine) returns ALLOW / DENY / REQUIRE_APPROVAL / ESCALATE. Map your client to whichever endpoint you call — do not assume allow/deny on /intent.

Authentication in one line#

Every non-operational route requires a verified tenant context. Present an intended_live_… API key (legacy mrt_… keys are still accepted) and the tenant header:

bash
curl https://api.intended.so/intents?tenantId=tenant_acme_prod \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod"

Only /health, /ready, and /.well-known/jwks.json are public. See Authentication for credential types, scopes, and every auth error.

Error conventions#

  • Validation failures return 400 with { "error": "VALIDATION_ERROR", "issues": [...] } (Zod issue array). Some routes use a route-specific code such as INVALID_POLICY_SET or INVALID_AUTHORITY_EVALUATION_REQUEST; the issues array is the same shape.
  • Authorization failures return 401 (no/invalid credential) or 403 (TENANT_MISMATCH, FORBIDDEN, IP_NOT_ALLOWED, MFA_REQUIRED).
  • Unhandled failures fail closed with a 500 and a route-specific code (e.g. AUTHORITY_LOOP_FAILED, AUDIT_QUERY_FAILED).

Info

The committed openapi.yaml is stale in several places — most notably the /intent decision enum, the /execute body, and the physical-token contract — and it omits the /verify/* routes. Where the spec and these pages disagree, the code (and these pages) win.

Next steps#

API Reference | Intended