Skip to content

api reference

Intended Documentation

API Reference: Intents

Submit intents to the authority runtime, inspect outcomes, and retrieve persisted intent records.

intermediate3 min readimplemented

Submit an Intent#

POST/intentRequires auth

Runs the authority loop for a compiled intent. The route returns one of three outcomes:

  • 200 approved path (token issued, execution attempted)
  • 202 escalated path (human approval required)
  • 403 denied path (fail-closed deny, no token)
tenantIdstring*Tenant identifier.
actorobject*Actor identity ({ id, type }).
targetSystemstring*Must match riskContext.github owner/repo as owner/repo.
proposedActionstring*Requested action description.
riskContextobject*Risk factors and GitHub target metadata.

Request Example#

bash
curl -X POST https://api.intended.so/intent \
  -H "Authorization: Bearer mrt_live_abc123" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "actor": { "id": "svc-ci-bot", "type": "service" },
    "targetSystem": "acme/platform-api",
    "proposedAction": "dispatch release workflow",
    "riskContext": {
      "baseRiskScore": 42,
      "policyCompliant": true,
      "requiresPrivilegedAccess": false,
      "touchesProduction": false,
      "containsSensitiveData": false,
      "github": {
        "owner": "acme",
        "repo": "platform-api",
        "ref": "refs/heads/main",
        "workflowId": "release.yml"
      }
    }
  }'

Response Example (Approved)#

json
{
  "intentId": "8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58",
  "correlationId": "a9d903e0-8b45-4a2f-9d30-6f9ce7d04d78",
  "authorityDecision": {
    "decision": "APPROVED",
    "riskScore": 42,
    "policyCompliant": true,
    "rationale": ["policy set passed"],
    "gateTrace": [{ "gate": "policy", "outcome": "PASSED", "reason": "matched allow rule" }]
  },
  "authorityDecisionToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS0xIn0...",
  "execution": {
    "attempted": true,
    "status": "executed",
    "adapterId": "github-actions-adapter"
  },
  "audit": {
    "entriesWritten": 5,
    "latestHash": "sha256:..."
  }
}

Response Example (Escalated)#

json
{
  "intentId": "8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58",
  "correlationId": "a9d903e0-8b45-4a2f-9d30-6f9ce7d04d78",
  "escalationId": "esc_123",
  "approvalRequestId": "apr_123",
  "authorityDecisionToken": null
}

List Intents#

GET/intentsRequires auth

List persisted intent records.

tenantIdstring*Tenant identifier.
limitnumber1-100 (default 25).
offsetnumberPagination offset.
decisionstringAPPROVED, ESCALATED, or DENIED.
bash
curl "https://api.intended.so/intents?tenantId=tenant_acme_prod&limit=20" \
  -H "Authorization: Bearer mrt_live_abc123"

Get Intent Detail#

GET/intents/:idRequires auth

Retrieve a single intent detail record.

idstring*Intent ID.
tenantIdstring*Tenant identifier.
bash
curl "https://api.intended.so/intents/8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58?tenantId=tenant_acme_prod" \
  -H "Authorization: Bearer mrt_live_abc123"

Simulate Without Persistence#

POST/intent/simulateRequires auth

Evaluates an intent using the same authority logic without minting tokens, executing adapters, or writing records.

Next Steps#