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
- Register Agent Identity
- Attach Authority Profile
- Define Policy
- Call
POST /v1/decisions - 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 (ALLOWorDENY)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.