API Reference

The Asqav REST API is available at https://api.asqav.com/api/v1. It provides AI agent governance capabilities including agent lifecycle management, guardrails, behavioral monitoring, compliance reports, incident management, observability, and policy enforcement -- all secured with ML-DSA (FIPS 204) signing.

Authentication

All API requests require your API key in the X-API-Key header:

curl https://api.asqav.com/api/v1/agents \
  -H "X-API-Key: sk_live_your_key"

API keys are prefixed with sk_live_ for live keys and sk_test_ for test keys. You can find and rotate your keys in the dashboard under Settings → API.

Getting Started

The typical workflow is: register an agent, issue a signed token, use that token to sign actions, and verify the signature chain later.

1. Register an agent

curl -X POST https://api.asqav.com/api/v1/agents \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "algorithm": "ml-dsa-65"}'

# Response
{
  "id": "agent_abc123",
  "name": "my-agent",
  "algorithm": "ml-dsa-65",
  "status": "active"
}

2. Sign an action

curl -X POST https://api.asqav.com/api/v1/agents/agent_abc123/sign \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "api:openai:chat", "context": {"model": "gpt-4", "tokens": 500}}'

# Response
{
  "signature_id": "sig_a1b2c3",
  "action_id": "act_xyz789",
  "signature": "base64-encoded-ml-dsa-signature",
  "timestamp": 1744488600.0,
  "verification_url": "https://api.asqav.com/api/v1/verify/sig_a1b2c3",
  "policy_digest": "sha256:2b1c3d...",
  "policy_decision": "permit",
  "authorization_ref": null
}

policy_digest, policy_decision, and authorization_ref let a third party reconstruct the exact JCS bytes that were signed and re-verify the signature offline. authorization_ref is populated with the approval ID when an approvals-queue approval authorized the action. Otherwise it is null.

Replay protection (nonce, valid_seconds)

POST /agents/{id}/sign accepts two optional fields that bind a signature to a single use and a finite window:

• nonce: opaque per-agent unique token, max 128 chars. Re-using the same (agent_id, nonce) pair is rejected, so a captured request body cannot be replayed.
• valid_seconds: validity window. Sets valid_until = signed_at + valid_seconds, clamped to 1..31_536_000.

curl -X POST https://api.asqav.com/api/v1/agents/agent_abc123/sign \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "api:openai:chat",
    "context": {"model": "gpt-4"},
    "nonce": "0c2c0d3e-7c6e-4c0a-9c3e-1a2b3c4d5e6f",
    "valid_seconds": 60
  }'

The verify endpoint rejects expired records with the signature_expired label, distinct from invalid_signature. See Proofs for the full label vocabulary.

Or use the Python SDK

import asqav

asqav.init(api_key="sk_your_api_key")

# Register agent
agent = asqav.Agent.create("my-agent", algorithm="ml-dsa-65")

# Sign an action
result = agent.sign("api:openai:chat")

Endpoint Reference

All paths are relative to https://api.asqav.com/api/v1. Pass your API key as -H "X-API-Key: sk_live_your_key" on every request.

Free (all plans)

Observability

Approvals

Replay

Guardrails

Compliance Reports

Governance

Enterprise

The endpoint groups below require the Enterprise plan.

Incidents and Escalation

Remediation

Multi-Party Signing

KMS, SSO, and access control

What's available by tier

Access to endpoints is gated by your plan. The table below shows which capability groups are included in each tier.

For the full list of endpoints, request parameters, and response schemas for your tier, open the dashboard API Reference tab.

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent with ID agent_abc123 not found",
    "status": 404
  }
}

API key scopes

Every API key carries a list of scopes that limit which endpoints it can reach. Pass "scopes": [...] in the POST /api/v1/keys body. Omitting the field (or passing null) gives the key the quickstart default set: agents:read, agents:write, sessions:read. Pass an explicit empty list to create a zero-scope key.

A request that hits a gated endpoint without the matching scope gets a 403 with a structured error body containing required_scope, how_to_fix, and docs_url. The wildcard * scope bypasses all per-resource checks.

Rate limits