Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getovra.com/llms.txt

Use this file to discover all available pages before exploring further.

An agent is a Stripe-shaped resource: it owns cards, tokens, transactions, and exactly one policy at a time. Agents are typed for AI use — they carry a purpose, optional framework (openai-assistants, anthropic-sdk, langgraph, crewai), and optional capabilities so the dashboard and audit trail can describe what they’re for.

​
The agent model

FieldDescription
idag_*
nameDisplay name
policyIdExactly one policy, mutable but always present
profile.purposeRequired. Free text — describe what the agent does.
profile.frameworkOptional — e.g. langgraph
profile.capabilitiesOptional string[] — what the agent can do
profile.descriptionOptional longer description
profile.departmentOptional cost-center tag
profile.ownerContactOptional escalation contact
statusactive · suspended · archived

​
Minimal create

The dashboard create drawer (and the documented happy path) is name + purpose + policyId. Other profile fields are optional, hidden behind an “Advanced” toggle. 
curl -X POST https://api.getovra.com/agents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "procurement-bot",
    "policyId": "po_default_...",
    "profile": { "purpose": "Buy office supplies under EUR 100" }
  }'

​
Lifecycle

EndpointPurpose
POST /agentsCreate (idempotent)
GET /agents/:idRead
PATCH /agents/:idUpdate name / profile / status
DELETE /agents/:idArchive (cascades over cards + tokens)
POST /agents/:id/freeze / /unfreezePause / resume authorization
POST /agents/:id/tokensIssue an agent-scoped token (at_*)

​
Agent tokens

Agents can hold their own scoped tokens (at_*). A token is bound to one agent, carries typed permissions, and may have an optional spend cap (via delegation). 
curl -X POST https://api.getovra.com/agents/ag_.../tokens \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-runtime",
    "scopes": ["intents.write", "checkout.write"],
    "expiresInDays": 90
  }'
Use at_* tokens in your runtime instead of sharing your org-level sk_* key. Cross-agent reads with an at_* token return 403 E_AGENT_ISOLATION — strict isolation is one of the sacred invariants.

​
Signing keys (Phase 8 prep)

For each agent, an Ed25519 keypair is provisioned async. The public JWK is exposed at: 
GET /.well-known/agent-jwks/{agent_id}
This is wiring for Visa Trusted Agent Protocol (RFC 9421 HTTP Message Signatures). No outbound signing is enabled in v1.2 — code lands when the first TAP-aware merchant requires it.

​
Webhooks

  • agent.created
  • agent.frozen
  • agent.unfrozen

​
Plan-tier limits

PlanAgents
Free1
Starter5
Business10
EnterpriseUnlimited

​
Surfaces

SurfaceCapability
REST/agents, /agents/:id/tokens
SDKovra.agents.*
MCPovra_agent (admin-side)
Dashboard/dashboard/agents

​
Next

Cards

Issue cards bound to an agent.

Policies

Define what an agent can spend.

Intents

The approval primitive every charge starts with.

Pay

How an agent actually pays.