> ## Documentation Index
> Fetch the complete documentation index at: https://docs.averta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Raw API integration

> Call Averta's runtime decision API directly from any programming language.

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](/dashboard/policies)
* 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](/concepts/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

```bash theme={null}
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:

```json theme={null}
{
  "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:

| Decision         | Adapter behavior                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `allow`          | Continue to the next step.                                                                                                      |
| `block`          | Stop before crossing the next boundary. Do not call the provider, execute the tool, send the tool result, or return the output. |
| `restrict_tools` | Remove `blocked_tools` from the provider tool list before provider execution.                                                   |
| `rewrite`        | For 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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](/concepts/images-and-rich-media) before relying on multimodal inputs.

## Endpoint Reference

<CardGroup cols={2}>
  <Card title="Create decision" icon="shield-check" href="/api-reference/endpoint/create-decision">
    Full request and response fields for `POST /v1/decide`.
  </Card>

  <Card title="Checkpoints" icon="git-branch" href="/concepts/checkpoints">
    Understand when each checkpoint runs.
  </Card>

  <Card title="Policies" icon="sliders" href="/concepts/policies">
    See how API keys map to enforcement.
  </Card>

  <Card title="Request context" icon="fingerprint" href="/concepts/request-context">
    Correlate API decisions with application logs.
  </Card>
</CardGroup>