Developers

Control API

Integrate ValarIQ before consequential financial actions execute. Canonical endpoint: POST /api/v1/decisions. Examples use placeholder identifiers only. Never paste live secrets into docs or tickets.

Vocabulary

  • Agent: autonomous financial actor
  • Agent Identity: cryptographic certificate and fingerprint
  • Authority Profile: delegated financial limits and permissions
  • Policy: rules evaluated at decision time
  • Financial Action: refund, payment, transfer, account change, etc.
  • Decision: ALLOW / ESCALATE / DENY
  • Evidence: signed Evidence Envelope
  • Approver: named human for ESCALATE outcomes

Quick start

  1. Register Agent Identity
  2. Attach Authority Profile
  3. Define Policy
  4. Call POST /v1/decisions
  5. Execute only on ALLOW (poll on ESCALATE)

Authentication

Control API uses Bearer keys (vq_live_… or staging equivalents). UI uses session cookies. Rotate and revoke keys per workspace. Do not embed real secrets in docs or tickets.

Canonical API: POST /v1/decisions

Evaluates Agent Identity, Authority Profile, and Policy for a Financial Action. HTTP status reflects whether ValarIQ completed the evaluation, not whether the agent may execute.

  • 200: decision completed (ALLOW or DENY)
  • 202: pending human Decision (ESCALATE)
  • 401 / 403: API authentication or access failure (not a ValarIQ financial Decision)
curl -X POST $VALARIQ_URL/api/v1/decisions \
  -H "authorization: Bearer $VALARIQ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
  "agent_id": "agt_demo_synthetic_01",
  "action": "refund.execute",
  "amount": 45.0,
  "currency": "GBP",
  "resource": "payment_synthetic_0001"
}'

ALLOW response (HTTP 200):

{
  "decision": "ALLOW",
  "authority_profile": "FinanceAgent-07",
  "risk_classification": "LOW",
  "evaluated_controls": [
    "Agent active",
    "Action within Agent Identity scopes",
    "Amount within auto-approve band",
    "Within Authority Profile and Policy"
  ],
  "evidence_id": "evd_…"
}

Observe Mode returns HTTP 200 with decision: ALLOW and observe_decision set to what Policy would have decided (DENY or ESCALATE). Production is not blocked.

ESCALATE response (HTTP 202):

{
  "decision": "ESCALATE",
  "authority_profile": "FinanceAgent-07",
  "risk_classification": "MEDIUM",
  "evaluated_controls": [
    "Agent active",
    "Action within Agent Identity scopes",
    "Amount requires Approver per workspace policy"
  ],
  "approval_id": "appr_…",
  "evidence_id": "evd_…"
}

DENY response (HTTP 200):

{
  "decision": "DENY",
  "authority_profile": "FinanceAgent-07",
  "risk_classification": "HIGH",
  "evaluated_controls": [
    "Agent active",
    "Amount exceeds Authority Profile limit"
  ],
  "reason": "exceeds_escalation_limit",
  "evidence_id": "evd_…"
}

Poll ESCALATE

curl "$VALARIQ_URL/api/v1/decisions?approval_id=<id>" \
  -H "authorization: Bearer $VALARIQ_API_KEY"

Evidence verification

Decision responses include evidence_id. Verify Agent Identity fingerprints via the verify endpoint below. Runtime event streams and customer webhooks are roadmap in production until the public capability register marks them operational.

Verify Agent Identity

curl -X POST $VALARIQ_URL/api/v1/verify \
  -H 'content-type: application/json' \
  -d '{"fingerprint":"<fp>"}'

SDK / Gateway package

A Node gateway client with wrapTool gates Financial Actions before execution. Integration packages and worked examples are provided for customer programmes. Contact hello@valariq.com.

import { createValarIQClient } from "@valariq/gateway";

const vq = createValarIQClient({
  baseUrl: process.env.VALARIQ_URL,
  apiKey: process.env.VALARIQ_API_KEY,
});

const refund = vq.wrapTool({
  fingerprint: process.env.AGENT_FINGERPRINT,
  action: "tools:refund",
  run: async (ctx) => yourPaymentProvider.refund(ctx),
});

Errors, idempotency & rate limits

  • 401/403: API auth only (not a financial DENY)
  • Idempotency: prefer stable client request identifiers where supported by your integration
  • Rate limits: enforced per key/workspace. Public numeric quota figures are not published.
  • OpenAPI / changelog: maintained with releases; check this page for current examples

Environments

Use a dedicated evaluation workspace for integration testing. Public operational claims follow the Capability Register. Treat evaluation screenshots as non-production unless confirmed for your deployment.

Workspace roles

  • viewer: read Agents, audit, monitor, Evidence
  • approver: resolve ESCALATE, create Evidence
  • admin: issue and revoke Agents and keys, invite people
  • owner: full workspace control

Legacy POST /api/v1/authorize remains for backwards compatibility only. New integrations must use /v1/decisions.

Workspace-specific policy thresholds and integration detail are provided in customer diligence packs. Defaults are not fixed in public documentation.

Samples: Evidence Envelope, Authority Profile, Policy rules.