Skip to content

guides

Intended Documentation

API Quickstart

Obtain an API key, submit your first intent, and handle approved, escalated, and denied outcomes.

beginner1 min readimplemented

API Quickstart#

This quickstart uses the canonical runtime route: POST /intent.

Step 1: Create an API Key#

Use a key scoped for tenant runtime operations and store it as local shell variables:

bash
export API_KEY="int_live_your_key_here"
export TENANT_ID="tenant_acme_prod"

Step 2: Submit an Intent#

bash
curl -X POST https://api.intended.so/intent \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-tenant-id: $TENANT_ID" \
  -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"
      }
    }
  }'

Step 3: Handle Outcome#

Approved (200)#

  • authorityDecision.decision = APPROVED
  • authorityDecisionToken is present
  • execution attempted through connector

Escalated (202)#

  • escalationId returned
  • no token is issued yet
  • complete human approval flow before execution

Denied (403)#

  • no token returned
  • execution is skipped (fail-closed)

Step 4: Retrieve Persisted Intent Record#

bash
curl "https://api.intended.so/intents?tenantId=$TENANT_ID&limit=10" \
  -H "Authorization: Bearer $API_KEY"
bash
curl "https://api.intended.so/intents/<intent-id>?tenantId=$TENANT_ID" \
  -H "Authorization: Bearer $API_KEY"

Next Steps#