Precipiq REST API reference

The Precipiq REST API is the foundation of the AI Consequences Ledger. Every endpoint lives under https://api.precipiq.dev/api/v1/ and returns a consistent JSON envelope so you can handle success and error paths the same way across your codebase.

Authentication

Every request requires an X-Precipiq-Key header. Keys come in two flavors:

pq_live_… — production keys that write to your live ledger
pq_test_… — sandbox keys for integration testing; data is isolated and never appears in production reports

curl -s https://api.precipiq.dev/api/v1/decisions \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

Missing or invalid keys return 401 with this body — the message is identical whether the header is absent or wrong, so an attacker cannot enumerate valid keys by response shape:

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or missing api key"
  }
}

Response envelope

All successful responses share the same outer shape. The data field contains the endpoint-specific payload; meta carries tracing information you can include in support tickets.

{
  "data": { },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-04-16T12:34:56.789012Z"
  }
}

Every response also sets an X-Request-ID header that mirrors meta.request_id. Include it when opening a support ticket. Error responses use a separate envelope:

{
  "error": {
    "code": "validation_error",
    "message": "confidence must be ≤ 1.0",
    "details": { }
  }
}

The optional details object contains field-level validation errors when code is validation_error.

Rate limits

Limits are applied per organization. Exceeding a limit returns 429 with a Retry-After value in the response.

Bucket	Limit	Endpoints
Single ingestion	100 req / s	`POST /decisions`, `POST /financial-events`, `POST /links`, `DELETE /links/{id}`
Batch ingestion	10 req / s	`POST /decisions/batch`
Reads	1,000 req / s	`GET /decisions`, `GET /links`, `GET /analytics/*`, `GET /decisions/chain/verify`
WebSocket handshake	30 req / min / IP	`/ws/v1/stream`

Use the batch endpoint (POST /decisions/batch) when ingesting bursts of decisions. You get 10 large calls per second instead of 100 individual ones, and the server preserves hash-chain order inside each batch.

Endpoints at a glance

Browse all endpoints by tag in the interactive reference below, or jump straight to a group:

decisions — /api/v1/decisions, /decisions/batch, /decisions/{id}, /decisions/chain/verify
financial-events — /api/v1/financial-events, /financial-events/webhook/stripe
consequence-links — /api/v1/links, /links/{id}, /links/{id}/confirm, /links/{id}/reject
analytics — /api/v1/analytics/ai-pnl, /analytics/timeline, /analytics/liability
exports — /api/v1/exports, /exports/{id}, /exports/{id}/download
websocket — /ws/v1/stream

Common calls

Every example below uses the placeholder key pq_test_demo_key_REPLACE_ME — substitute your own key from the dashboard before running.

Ingest a single decision

POST /api/v1/decisions

curl -X POST https://api.precipiq.dev/api/v1/decisions \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "pricing-bot",
    "action_type": "discount_offer",
    "inputs":  {"customer_id": "cust_123", "tier": "gold"},
    "outputs": {"discount_pct": 15},
    "confidence": 0.82,
    "human_in_loop": false
  }'

import httpx

r = httpx.post(
    "https://api.precipiq.dev/api/v1/decisions",
    headers={"X-Precipiq-Key": "pq_test_demo_key_REPLACE_ME"},
    json={
        "agent_id": "pricing-bot",
        "action_type": "discount_offer",
        "inputs":  {"customer_id": "cust_123", "tier": "gold"},
        "outputs": {"discount_pct": 15},
        "confidence": 0.82,
        "human_in_loop": False,
    },
    timeout=10.0,
)
r.raise_for_status()
print(r.json()["data"]["decision_id"])

const res = await fetch(
  'https://api.precipiq.dev/api/v1/decisions',
  {
    method: 'POST',
    headers: {
      'X-Precipiq-Key': 'pq_test_demo_key_REPLACE_ME',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: 'pricing-bot',
      action_type: 'discount_offer',
      inputs:  { customer_id: 'cust_123', tier: 'gold' },
      outputs: { discount_pct: 15 },
      confidence: 0.82,
      human_in_loop: false,
    }),
  },
);
if (!res.ok) throw new Error(`ingest failed: ${res.status}`);
const body = await res.json();
console.log(body.data.decision_id);

Ingest a batch of decisions

POST /api/v1/decisions/batch — send up to 100 decisions in a single call.

curl -X POST https://api.precipiq.dev/api/v1/decisions/batch \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "decisions": [
      {"agent_id":"a","action_type":"t","inputs":{},"outputs":{},"confidence":0.9,"human_in_loop":false},
      {"agent_id":"a","action_type":"t","inputs":{},"outputs":{},"confidence":0.8,"human_in_loop":false}
    ]
  }'

httpx.post(
    "https://api.precipiq.dev/api/v1/decisions/batch",
    headers={"X-Precipiq-Key": "pq_test_demo_key_REPLACE_ME"},
    json={"decisions": [decision1, decision2]},
    timeout=10.0,
).raise_for_status()

List decisions with cursor pagination

GET /api/v1/decisions?agent_id=&action_type=&start=&end=&cursor=

curl

curl -s 'https://api.precipiq.dev/api/v1/decisions?agent_id=pricing-bot' \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

The response’s data.next_cursor is an opaque string. Pass it back verbatim as ?cursor=… to fetch the next page. Results are ordered newest first (timestamp DESC, id DESC), and the cursor guarantees no rows are skipped or duplicated across pages.

Verify the hash chain

GET /api/v1/decisions/chain/verify?start_date=&end_date=

curl

curl -s https://api.precipiq.dev/api/v1/decisions/chain/verify \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

Returns is_valid, records_checked, first_broken_link, and verification_timestamp. See Hash Chain for the semantics.

Ingest a financial event

POST /api/v1/financial-events

curl

curl -X POST https://api.precipiq.dev/api/v1/financial-events \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "internal",
    "event_type": "payment",
    "amount": "149.00",
    "currency": "USD",
    "external_id": "invoice_0042",
    "timestamp": "2026-04-16T12:35:02Z"
  }'

Link a decision to a financial event

POST /api/v1/links

curl

curl -X POST https://api.precipiq.dev/api/v1/links \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "decision_id":         "d5e7a3b0-0000-0000-0000-000000000001",
    "financial_event_id":  "fev_abc",
    "correlation_strength": 1.0,
    "attribution_method":   "direct",
    "link_type":            "revenue",
    "notes":                "upsell offer accepted"
  }'

Confirm or reject a suggested link

POST /api/v1/links/{id}/confirm and POST /api/v1/links/{id}/reject These endpoints are used when a human reviews a link with status ML_SUGGESTED. Confirming flips it to ML_INFERRED and nudges the Bayesian priors; rejecting soft-deletes it and nudges them the other way.

curl

curl -X POST https://api.precipiq.dev/api/v1/links/${LINK_ID}/confirm \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

Fetch the AI P&L

GET /api/v1/analytics/ai-pnl?start=&end=&agent_id=

curl

curl -s 'https://api.precipiq.dev/api/v1/analytics/ai-pnl?start=2026-04-01&end=2026-04-30' \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

Aggregate liability exposure

GET /api/v1/analytics/liability

curl

curl -s https://api.precipiq.dev/api/v1/analytics/liability \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME'

Create and download a forensic export

POST /api/v1/exports → GET /api/v1/exports/{id} → GET /api/v1/exports/{id}/download Forensic exports are generated asynchronously. Start the job, poll until it completes, then download the signed bundle.

curl

# 1. Start the export.
EXPORT_ID=$(curl -s -X POST https://api.precipiq.dev/api/v1/exports \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{"export_type":"forensic","start_date":"2026-01-01T00:00:00Z","end_date":"2026-03-31T23:59:59Z"}' \
  | jq -r .data.export_id)

# 2. Poll until complete.
while true; do
  STATUS=$(curl -s "https://api.precipiq.dev/api/v1/exports/$EXPORT_ID" \
    -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' | jq -r .data.status)
  [ "$STATUS" = "complete" ] && break
  sleep 5
done

# 3. Download the signed bundle.
curl -s "https://api.precipiq.dev/api/v1/exports/$EXPORT_ID/download" \
  -H 'X-Precipiq-Key: pq_test_demo_key_REPLACE_ME' \
  -o precipiq-export.zip

The download URL in the response is a pre-signed link with a limited TTL. Download the file promptly after the export reaches complete status.

REST API

SDKs

Releases

Precipiq REST API reference

Authentication

Response envelope

Rate limits

Endpoints at a glance

Common calls

Ingest a single decision

Ingest a batch of decisions

Verify the hash chain

Ingest a financial event

Link a decision to a financial event

Confirm or reject a suggested link

Fetch the AI P&L

Aggregate liability exposure

Create and download a forensic export

​Authentication

​Response envelope

​Rate limits

​Endpoints at a glance

​Common calls

​Ingest a single decision

​Ingest a batch of decisions

​List decisions with cursor pagination

​Verify the hash chain

​Ingest a financial event

​Link a decision to a financial event

​Confirm or reject a suggested link

​Fetch the AI P&L

​Aggregate liability exposure

​Create and download a forensic export

Authentication

Response envelope

Rate limits

Endpoints at a glance

Common calls

Ingest a single decision

Ingest a batch of decisions

List decisions with cursor pagination

Verify the hash chain

Ingest a financial event

Link a decision to a financial event

Confirm or reject a suggested link

Fetch the AI P&L

Aggregate liability exposure

Create and download a forensic export