Docs

Control API

Technical reference for engineering. Wire ValarIQ into an agent runtime. Canonical endpoint: POST /api/v1/decisions.

Quick start

1. Register agent
2. Create Authority Profile
3. Define policy
4. Evaluate Financial Action
5. Execute on ALLOW (or poll ESCALATE)

1. POST /v1/decisions

Canonical Control API. Evaluates identity, delegated authority, and transaction policy. Returns ALLOW, ESCALATE, or DENY with explainable policy signals — not opaque scoring.

curl -X POST $VALARIQ_URL/api/v1/decisions \
  -H "authorization: Bearer $VALARIQ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
  "agent_id": "agt_finance_07",
  "action": "refund.execute",
  "amount": 247.50,
  "currency": "GBP",
  "resource": "payment_82372"
}'

Response:

{
  "decision": "ESCALATE",
  "risk_classification": "MEDIUM",
  "authority": "refund_standard",
  "policy_id": "REFUND_STANDARD_01",
  "signals": {
    "amount_threshold": "pass — escalate band",
    "destination": "pass",
    "agent_authority": "pass"
  },
  "approval_id": "appr_…",
  "evidence_id": null
}

Legacy POST /api/v1/authorize remains supported for existing gateway clients. Prefer /v1/decisions for new integrations.

2. Verify identity

Check that a fingerprint belongs to an active agent certificate.

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

3. Workspace policy

Configure thresholds, observe vs enforce mode, and kill switch via Agents → Policy or PATCH /api/workspace/policy. Default refund bands: auto-approve up to £100, escalate to £500, deny above.

4. Poll approval (ESCALATE)

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

5. Gateway package

Use @valariq/gateway with wrapTool or gateToolCall so every Financial Action hits ValarIQ before execution.

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

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

const execute = vq.wrapTool({
  fingerprint: process.env.AGENT_FINGERPRINT,
  action: "tools:payment.execute",
  run: async (payment) => bank.transfer(payment),
});

High-risk scopes

Default to ESCALATE when no policy rule applies: tools:payment.execute, tools:payment.initiate, tools:refund (policy may ALLOW low amounts), tools:kyc.write, tools:account.write, tools:crm.write, tools:email, tools:beneficiary.write, tools:treasury.transfer.

Vocabulary

• Agent — autonomous financial actor with a certificate
• Authority Profile — delegated financial limits and permissions
• Policy — rules evaluated at decision time
• Decision — ALLOW / ESCALATE / DENY
• Evidence Envelope — signed proof of the decision trail

Workspace roles

• viewer: read agents, audit, monitor, evidence
• approver: approve or deny ESCALATE outcomes, create evidence
• admin: issue and revoke agents and keys, invite people
• owner: full control of the workspace

Sample downloads: Evidence Envelope, Authority Profile, Policy rules.