Quickstart

This quickstart walks the agent integration loop end to end with curl. You need:

• An agent key — an operator creates an AI agent connection in the console (see Using the platform → Agent connections) and gives you the key.
• The API base URL — https://af-api.ivalt.com on the hosted platform.

You don't need to configure routing to get started: every workspace ships with a built-in default approval path.

Wire formatCopy Anchor Link

Every agent API call is an HTTP POST:

POST /api/v1/ai-agent/<procedure>
x-ai-agent-key: <agent-key>
Content-Type: application/json

{"json": { <input> }}

Success responses are {"json": { <output> }}; failures return a structured error object — see Errors.

1. Check the connection identityCopy Anchor Link

curl -s -X POST https://af-api.ivalt.com/api/v1/ai-agent/getIdentity \
  -H 'content-type: application/json' \
  -H 'x-ai-agent-key: <agent-key>' \
  -d '{"json":{}}'

Response:

{
  "json": {
    "id": "pc_a1b2c3d4e5f6",
    "tenantId": "org_example",
    "name": "Correspondence Agent",
    "deliveryConfig": { "polling": true, "webhook": true }
  }
}

deliveryConfig tells you which delivery modes apply to your requests — polling is always on; webhook means you can also receive signed approval.completed callbacks.

2. Submit an authority requestCopy Anchor Link

curl -s -X POST https://af-api.ivalt.com/api/v1/ai-agent/submitRequest \
  -H 'content-type: application/json' \
  -H 'x-ai-agent-key: <agent-key>' \
  -d '{
    "json": {
      "externalRequestId": "REQ-1001",
      "idempotencyKey": "<a fresh uuid>",
      "title": "On-behalf-of correspondence",
      "actionType": "send_mail",
      "actionSummary": "Send signed correspondence to Meridian Mutual.",
      "displaySnapshot": { "recipient": "meridian@example.com", "amount": 4500 },
      "contentHash": "sha256:<hash of the full action content>",
      "expiresAt": "2026-11-17T22:00:00.000Z",
      "riskLevel": "high"
    }
  }'

The json.id in the response is the request ID used by every later call. idempotencyKey is unique per connection: retrying with the same key and payload replays the original response — mint one key per logical request, not per attempt. A different payload under the same key returns idempotency_conflict.

One optional field controls where the request lands:

• recipientUserId — send the request directly to a specific approver (the user ID from People & roles in the console), bypassing routing. Omitted above, so the request uses the default approval path.

3. Poll for the decisionCopy Anchor Link

curl -s -X POST https://af-api.ivalt.com/api/v1/ai-agent/getStatus \
  -H 'content-type: application/json' \
  -H 'x-ai-agent-key: <agent-key>' \
  -d '{"json":{"requestId":"<request-id>"}}'

getStatus returns { request, isFinal, deliveryModes, reviewProgress, receiptId, nextPollAfterMs }. Poll at nextPollAfterMs intervals until isFinal is true — final statuses are approved, rejected, and expired. While a request is pending, the assigned approver reviews it in the TrustLoop app, verifies their identity, and records a decision.

If webhook delivery is enabled on the connection, you also receive a signed approval.completed callback — see Webhooks.

4. Fetch the signed proofCopy Anchor Link

curl -s -X POST https://af-api.ivalt.com/api/v1/ai-agent/getProof \
  -H 'content-type: application/json' \
  -H 'x-ai-agent-key: <agent-key>' \
  -d '{"json":{"requestId":"<request-id>"}}'

The receipt carries signature, keyId, verificationRule: "local-ed25519", and a referenceId of the form AUTH-<externalRequestId>. Verify it before performing the protected action — the full recipe is in Receipts. For a request with no final decision yet, getProof returns not_found.

Next stepsCopy Anchor Link

• Requests — the full polling recipe.
• Webhooks — receive approval.completed instead of polling.
• API reference — full schemas for every agent procedure.