Developers

Control API

Wire ValarIQ into an agent runtime. One canonical endpoint: POST /api/v1/decisions. Examples use synthetic identifiers. Never paste production secrets.

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 webhooks: Coming. Not claimed Live until the capability registry says so.

Verify Agent Identity

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

SDK / Gateway package

Node gateway client (@valariq/gateway) with wrapTool gates Financial Actions before execution. Package distribution is source-only until an explicit npm release; contact hello@valariq.com for integration packages and worked examples.

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) => stripe.refunds.create(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. Treat as Coming for public numeric quotas
• OpenAPI / changelog: maintained with releases; check this page and git history

Environments

Staging may expose Foundation capabilities. Production Live claims come only from the capability registry after ordered deploy + smoke. Do not assume staging screenshots are production.

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 design-partner diligence packs. Defaults are not fixed in public documentation.

Samples: Evidence Envelope, Authority Profile, Policy rules.