Skip to main content
Use the raw API when your agent cannot use an Averta provider wrapper or core SDK package. This is the path for Go, Rust, Java, C#, Elixir, or any runtime where you want to own the HTTP calls. The raw API gives you the same checkpoint model as the SDK wrappers, but your adapter must enforce every decision correctly.

​
Before You Start

You need:
  • an Averta API key with an attached policy
  • a provider API key for the model you already use
  • code that can call POST https://api.averta.io/v1/decide
  • stable IDs for request context
If the Averta key has no policy attached, the integration is not a guarded setup.

​
Request Flow

Call Averta before and after the provider operations your agent performs:
  1. Call the request checkpoint before the provider sees user input.
  2. If the decision is block, stop before the provider call.
  3. If the decision is restrict_tools, remove the blocked tools, then call the provider with the reduced tool list.
  4. If the model requests a tool, call the tool_call checkpoint before executing it.
  5. After your tool returns data, call the tool_result checkpoint before sending that data back to the model.
  6. When the provider returns final text, call the output checkpoint before returning it to the user.
That ordering matters. Calling the provider first and checking later leaves the risky boundary unguarded.

​
Minimal Request Check

curl https://api.averta.io/v1/decide \
  -H "Authorization: Bearer $AVERTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoint_type": "request",
    "client": {
      "type": "api",
      "name": "my-agent",
      "version": "1.0.0"
    },
    "provider": {
      "name": "custom",
      "operation": "messages.create",
      "model": "agent-model",
      "streaming": false
    },
    "request_context": {
      "conversation_id": "conversation_123",
      "request_id": "request_456",
      "trace_id": "trace_789"
    },
    "payload": {
      "text": "Can you reset my password?"
    }
  }'
An allowed response lets the provider call continue: 
{
  "decision": "allow",
  "decision_id": "dec_123",
  "event_id": "evt_123",
  "policy_id": "pol_123",
  "reasons": [],
  "run_id": "run_123"
}

​
Decision Handling

Your adapter must handle every valid decision for the checkpoint it calls:
DecisionAdapter behavior
allowContinue to the next step.
blockStop before crossing the next boundary. Do not call the provider, execute the tool, send the tool result, or return the output.
restrict_toolsRemove blocked_tools from the provider tool list before provider execution.
rewriteFor output checkpoints, request a safer replacement and check that rewritten output once.
If the API call fails and your app cannot prove a safe decision, fail closed.

​
Tool Filtering

For tool-using agents, send tools on the request checkpoint: 
{
  "checkpoint_type": "request",
  "payload": {
    "text": "Email the customer a refund confirmation."
  },
  "tools": [
    {
      "name": "lookup_order",
      "type": "function",
      "description": "Look up an order."
    },
    {
      "name": "send_email",
      "type": "function",
      "description": "Send an email to a customer."
    }
  ]
}
If Averta returns: 
{
  "decision": "restrict_tools",
  "blocked_tools": ["send_email"],
  "run_id": "run_123"
}
your adapter must remove send_email before calling the provider.

​
Media

For image-capable adapters, send supported images in the request checkpoint media array. Keep text in payload.text. 
{
  "checkpoint_type": "request",
  "payload": {
    "text": "Inspect this screenshot."
  },
  "media": [
    {
      "id": "image_1",
      "kind": "image",
      "mime_type": "image/png",
      "data_base64": "iVBORw0KGgo="
    }
  ]
}
See Images and rich media before relying on multimodal inputs.

​
Endpoint Reference

Create decision

Full request and response fields for POST /v1/decide.

Checkpoints

Understand when each checkpoint runs.

Policies

See how API keys map to enforcement.

Request context

Correlate API decisions with application logs.