QUICKSTART.
AUTH. FULL
REFERENCE.

AUTHENTICATION

SIGN EVERY REQUEST.

Every request to /api/agents requires a Truss API key. Pass it in either of the two accepted header forms — both are equivalent:

Authorization: Bearer truss_<your-48-hex-key>

x-api-key: truss_<your-48-hex-key>

Auth failure responses:

POST /api/agents
REFERENCE

POST https://api.truss.polsia.app/api/agents

Auth: Authorization: Bearer <key> or x-api-key: <key> (required)
Content-Type: application/json

Request Body Fields

Three-Way Match Mode verdict

Add "mode": "three_way_match" to the request body to cross-check a purchase order, invoice, and receipt in a single synchronous call. Truss compares each document’s amount, vendor_name, and date (case/space-insensitive) and returns one of four verdicts:

Three-Way Match Body

curl -X POST https://api.truss.polsia.app/api/agents \
  -H "Authorization: Bearer truss_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "three_way_match",
    "po":      { "po_number": "PO-001", "amount": 100.00, "vendor_name": "Acme", "date": "2026-07-01" },
    "invoice": {                      "amount": 100.00, "vendor_name": "Acme", "date": "2026-07-01" },
    "receipt": {                      "amount": 100.00, "vendor_name": "Acme", "date": "2026-07-01" }
  }'

// 200 OK — all three line up
{
  "authenticated": true,
  "owner_label": "your-key-label",
  "invocation_id": 123,
  "verification": {
    "mode": "three_way_match",
    "verdict": "verified",
    "verified": true,
    "missing_documents": [],
    "comparisons": [
      { "field": "amount",      "matched": true,  "values": { "po": 100,    "invoice": 100,    "receipt": 100 } },
      { "field": "vendor_name", "matched": true,  "values": { "po": "Acme",  "invoice": "Acme",  "receipt": "Acme" } },
      { "field": "date",        "matched": true,  "values": { "po": "2026-07-01", "invoice": "2026-07-01", "receipt": "2026-07-01" } }
    ],
    "matched_fields": [...],
    "anomalies": [],
    "checked_at": "2026-08-22T12:00:00.000Z"
  }
}

Every successful response includes an invocation_id. Keep this ID with the result if a callback is configured; it is the correlation ID for checking delivery status.

When an amount mismatch is detected, the verdict flips to "mismatch" (or "partial" if other cross-checks still line up) and verification.anomalies surfaces the offending field with the per-document values, e.g.:

{
  "verification": {
    "mode": "three_way_match",
    "verdict": "mismatch",
    "verified": false,
    "missing_documents": [],
    "comparisons": [
      { "field": "amount", "matched": false, "values": { "po": 100, "invoice": 110, "receipt": 130 } },
      ...
    ],
    "anomalies": [{ "field": "amount", "severity": "error", "values": {...} }],
    ...
  }
}

Webhook Callbacks

When a valid webhook_url is active, Truss returns the verdict synchronously and asynchronously POSTs the same response envelope to that URL. The callback adds the top-level API-key tier; its nested verification object is unchanged, including all three-way match fields.

// POST to your webhook_url
{
  "authenticated": true,
  "owner_label": "your-key-label",
  "invocation_id": 123,
  "verification": {
    "mode": "three_way_match",
    "verdict": "verified",
    "verified": true,
    "missing_documents": [],
    "comparisons": [
      { "field": "amount", "matched": true, "values": { "po": 100, "invoice": 100, "receipt": 100 } },
      { "field": "vendor_name", "matched": true, "values": { "po": "Acme", "invoice": "Acme", "receipt": "Acme" } },
      { "field": "date", "matched": true, "values": { "po": "2026-07-01", "invoice": "2026-07-01", "receipt": "2026-07-01" } }
    ],
    "matched_fields": [ ... ],
    "anomalies": [],
    "checked_at": "2026-08-22T12:00:00.000Z"
  },
  "tier": "paid"
}

Truss sends the case-insensitive X-Truss-Signature header in the format sha256=<lowercase-hex-digest>. The digest is an HMAC-SHA256 made with the API key’s plaintext value as the secret and the exact UTF-8 JSON request body as the message. Verify the signature against the raw body before parsing JSON. For Python and Node.js request examples, see the SDK examples. The callback includes the same top-level invocation_id as the inline response. Any 2xx response counts as delivered; non-2xx responses, timeouts, and network errors are retried up to three total attempts with short backoff (100ms, then 200ms). A final failure is recorded, but never delays or changes the inline verdict response.

Webhook Delivery Status

Poll delivery state with the invocation_id returned by POST /api/agents. This endpoint uses the same API key, so an invocation belonging to another key is indistinguishable from an unknown ID. The public delivery_state enum is not_configured, retrying, delivered, or permanently_failed. The persisted internal pending state is returned as retrying until delivery settles.

curl https://api.truss.polsia.app/api/agents/123/webhook-status \
  -H "Authorization: Bearer truss_<your-key>"

// 200 OK
{
  "invocation_id": 123,
  "delivery_state": "retrying",
  "attempt_count": 2,
  "created_at": "2026-08-22T12:00:00.000Z",
  "delivered_at": null,
  "latest_failure_reason": "HTTP 502"
}

Delivery makes one immediate attempt, then retries after 100ms and 200ms, for three total attempts. A retry count is therefore max(attempt_count - 1, 0).

When a callback is configured, retrying is the transient state to poll, including the internal pending period and the backoff between attempts. Stop when it settles at the terminal delivered or permanently_failed state; for permanent failure, use latest_failure_reason as the terminal error. not_configured is also terminal. A malformed, nonexistent, or other-account invocation returns 404 with {"error":"Invocation not found"}. Missing or invalid credentials retain the standard 401 responses.

SDK-Style Receiver

Register this route before a global express.json() parser so the raw request bytes remain available:

const crypto = require('node:crypto');
const express = require('express');
const app = express();
const TRUSS_API_KEY = process.env.TRUSS_API_KEY;

app.post('/truss/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const received = req.get('X-Truss-Signature') || '';
    const expected = 'sha256=' + crypto
      .createHmac('sha256', TRUSS_API_KEY)
      .update(req.body)
      .digest('hex');
    const valid = received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
    if (!valid) return res.sendStatus(401);

    const callback = JSON.parse(req.body.toString('utf8'));
    // callback.verification.verdict is ready for your async workflow.
    console.log(callback.tier, callback.verification);
    return res.sendStatus(204);
  }
);

Response Shape

{
  "authenticated": true,
  "owner_label": "your-key-label",
  "verification": {
    "verified": false,
    "invoice_id": null,
    "payment_id": null,
    "matched_fields": [],
    "anomalies": [
      {
        "field": "invoice_id",
        "severity": "error",
        "message": "invoice_id is required"
      }
    ],
    "checked_at": "2026-08-21T12:00:00.000Z"
  }
}

Each entry in anomalies carries field, severity ("error" or "warning"), and optionally expected, actual, and message. verified is true only when the invoice and payment both resolve and no error-severity anomalies fire.

Status Codes

For the exact failure bodies and the corrective action for each status, see the API error reference.

How Results Map to /api_invocations

Every authenticated call — including verified: false outcomes — is logged to api_invocations and visible in the /dashboard/api-usage view. The verification object is stored in response_payload; the verified flag and anomaly count are surfaced as columns in that dashboard so you can audit all agent traffic and spot mismatches before they reach payment.