API reference

Governed interactions

Record a governed AI action as a Trust Atom. Recon evaluates your Policy, returns a decision, issues a Trust Receipt, and appends a Ledger entry under the same correlationId.

Request

POST /v1/governed-interactions

curl -X POST "$RECON_API_BASE_URL/v1/governed-interactions" \
  -H "Authorization: Bearer recon_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: org_recon_test" \
  -d '{
    "integrationId": "int_quickstart_v1",
    "clientRequestId": "creq_a1b2c3d4e5f67890",
    "actionType": "governed_ai_action",
    "policyId": "policy_quickstart"
  }'

Required body fields: integrationId, clientRequestId, actionType. Optional: policyId, payload.

Retry with the same clientRequestId for idempotent replay.

Response

Customer-facing fields: decision, correlation identity, Trust Receipt reference, and Ledger reference.

{
  "correlationId": "tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8",
  "orgId": "org_recon_test",
  "decision": "permit",
  "policyId": "policy_quickstart",
  "decidedAt": "2026-08-15T18:30:00.000Z",
  "receiptId": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "issuedAt": "2026-08-15T18:30:00.001Z",
  "atom": {
    "actionType": "governed_ai_action",
    "integrationId": "int_quickstart_v1",
    "clientRequestId": "creq_a1b2c3d4e5f67890"
  },
  "ledger": {
    "entryId": "b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567890",
    "appendedAt": "2026-08-15T18:30:00.002Z"
  },
  "links": {
    "receipt": "/v1/trust-receipts/tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8",
    "ledger": "/v1/ledger/entries/tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8"
  }
}

Trust Receipts

Fetch a Trust Receipt by correlation identity. The POST response includes links.receipt.

GET /v1/trust-receipts/tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8

{
  "correlationId": "tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8",
  "orgId": "org_recon_test",
  "receiptId": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "issuedAt": "2026-08-15T18:30:00.001Z",
  "decision": "permit",
  "policyId": "policy_quickstart",
  "atom": {
    "actionType": "governed_ai_action",
    "integrationId": "int_quickstart_v1",
    "clientRequestId": "creq_a1b2c3d4e5f67890"
  }
}

Inspect in the dashboard: /trust-receipts/tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8

Ledger

Verify the append-only Ledger entry for the same Trust Atom. The POST response includes links.ledger.

GET /v1/ledger/entries/tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8

{
  "correlationId": "tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8",
  "orgId": "org_recon_test",
  "entryId": "b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567890",
  "appendedAt": "2026-08-15T18:30:00.002Z",
  "receiptId": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "decision": "permit"
}

Open in the Ledger UI: /ghostlog?highlight=tacorr_8f3a2b1c4d5e6f708192a3b4c5d6e7f8

Authentication

• Send Authorization: Bearer recon_live_* on every request. Get an API key.
• Scope requests to your organization with X-Org-ID or X-Recon-Org-Id. The header must match your key's org scope.
• POST /v1/governed-interactions requires the missions:write scope. Receipt and Ledger reads require audit:read.

Errors

Recon fails closed. Denied actions still return a Trust Receipt and Ledger entry when the interaction is recorded.

• 401 — Invalid API key. Check your Recon key and try again.
• 403 — This key is not authorized for the requested organization.
• 422 — Missing required fields or invalid JSON body.
• 503 — Recon could not record this interaction. Retry with the same client request ID.

Advanced

SDK adapters and legacy endpoints are available for deeper integrations.

• @reconai/sdk — npm package for agent wrappers
• reconai-langchain — Python adapter (GitHub)