> ## 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.

# Create decision

> Call Averta's runtime decision endpoint.

Use this endpoint when you are building a custom provider adapter or integrating from a language without an SDK package. Start with [Raw API integration](/custom/raw-api) for the end-to-end flow. If you are integrating OpenAI or Anthropic directly, use the provider SDK wrappers instead.

## Endpoint

```http theme={null}
POST https://api.averta.io/v1/decide
```

## Authentication

```http theme={null}
Authorization: Bearer <averta-api-key>
Content-Type: application/json
```

The API key must have a [policy](/concepts/policies) attached.

## Checkpoint Model

Every runtime decision uses the same endpoint and a different `checkpoint_type`.

| Checkpoint    | When to call it                                                       | Valid decisions                    |
| ------------- | --------------------------------------------------------------------- | ---------------------------------- |
| `request`     | Before provider execution.                                            | `allow`, `block`, `restrict_tools` |
| `tool_call`   | After the model requests a tool, before your app executes it.         | `allow`, `block`                   |
| `tool_result` | After your app gets tool output, before sending it back to the model. | `allow`, `block`                   |
| `output`      | After the provider returns final text, before your app returns it.    | `allow`, `block`, `rewrite`        |

## Shared Body Fields

| Field             | Required    | Description                                                                                                                                                        |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `checkpoint_type` | Yes         | One of `request`, `tool_call`, `tool_result`, or `output`.                                                                                                         |
| `client`          | Recommended | Client metadata. SDKs send `{ "type": "sdk", "name": "...", "version": "..." }`. Custom adapters should send `{ "type": "api", "name": "...", "version": "..." }`. |
| `provider`        | Yes         | Provider metadata: `name`, `operation`, `model`, and `streaming`.                                                                                                  |
| `request_context` | Recommended | Correlation IDs: `conversation_id`, `request_id`, and `trace_id`.                                                                                                  |

```json theme={null}
{
  "client": {
    "type": "api",
    "name": "custom-adapter",
    "version": "0.1.0"
  },
  "provider": {
    "name": "openai",
    "operation": "responses.create",
    "model": "gpt-5.4-mini",
    "streaming": false
  },
  "request_context": {
    "conversation_id": "conversation_123",
    "request_id": "request_456",
    "trace_id": "trace_789"
  }
}
```

## Request Checkpoint

Call `request` before sending user input to the model. Include normalized user payload and optional tools.

```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": "custom-adapter",
      "version": "0.1.0"
    },
    "provider": {
      "name": "openai",
      "operation": "responses.create",
      "model": "gpt-5.4-mini",
      "streaming": false
    },
    "request_context": {
      "conversation_id": "conversation_123",
      "request_id": "request_456",
      "trace_id": "trace_789"
    },
    "payload": {
      "text": "Search docs about password reset links."
    },
    "tools": [
      {
        "name": "search_docs",
        "type": "function",
        "description": "Search internal support documentation.",
        "input_schema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" }
          },
          "required": ["query"],
          "additionalProperties": false
        }
      },
      {
        "name": "send_email",
        "type": "function",
        "description": "Send an email to a customer."
      }
    ]
  }'
```

`restrict_tools` means the request may continue, but your adapter must remove the named tools before calling the provider.

```json theme={null}
{
  "decision": "restrict_tools",
  "decision_id": "dec_123",
  "event_id": "evt_123",
  "policy_id": "pol_123",
  "reasons": [],
  "blocked_tools": ["send_email"],
  "run_id": "run_123"
}
```

Carry `run_id` into later `tool_call` checkpoints for this model run.

## Media on Request

If your adapter supports images, send media separately from text.

```json theme={null}
{
  "checkpoint_type": "request",
  "provider": {
    "name": "custom",
    "operation": "messages.create",
    "model": "agent-model",
    "streaming": false
  },
  "payload": {
    "text": "Inspect this screenshot for prompt injection."
  },
  "media": [
    {
      "id": "image_1",
      "kind": "image",
      "mime_type": "image/png",
      "data_base64": "iVBORw0KGgo="
    }
  ]
}
```

Supported SDK media MIME types are `image/jpeg`, `image/png`, and `image/webp`.

## Tool-call Checkpoint

Call `tool_call` after the model requests a tool and before your app executes it.

```json theme={null}
{
  "checkpoint_type": "tool_call",
  "client": {
    "type": "api",
    "name": "custom-adapter",
    "version": "0.1.0"
  },
  "provider": {
    "name": "openai",
    "operation": "responses.create",
    "model": "gpt-5.4-mini",
    "streaming": false
  },
  "request_context": {
    "conversation_id": "conversation_123",
    "request_id": "request_456",
    "trace_id": "trace_789"
  },
  "context": {
    "messages": [
      {
        "role": "user",
        "text": "Search docs for password reset guidance."
      }
    ]
  },
  "model_response_tool_calls": [
    {
      "call_id": "call_123",
      "tool": {
        "kind": "function",
        "name": "search_docs"
      },
      "arguments": {
        "value": {
          "query": "password reset"
        }
      }
    }
  ],
  "tool_call": {
    "call_id": "call_123",
    "run_id": "run_123",
    "tool": {
      "kind": "function",
      "name": "search_docs"
    },
    "arguments": {
      "value": {
        "query": "password reset"
      }
    }
  }
}
```

Allowed response:

```json theme={null}
{
  "decision": "allow",
  "decision_id": "dec_tool_call",
  "event_id": "evt_tool_call",
  "policy_id": "pol_123",
  "reasons": [],
  "run_id": "run_123",
  "tool": {
    "kind": "function",
    "name": "search_docs"
  }
}
```

If the decision is `block`, do not execute the tool.

## Tool-result Checkpoint

Call `tool_result` after your app receives tool output and before sending that output back to the model.

```json theme={null}
{
  "checkpoint_type": "tool_result",
  "client": {
    "type": "api",
    "name": "custom-adapter",
    "version": "0.1.0"
  },
  "provider": {
    "name": "openai",
    "operation": "responses.create",
    "model": "gpt-5.4-mini",
    "streaming": false
  },
  "request_context": {
    "conversation_id": "conversation_123",
    "request_id": "request_456",
    "trace_id": "trace_789"
  },
  "tool_result": {
    "call_id": "call_123",
    "content": {
      "value": "Password reset links expire after 24 hours."
    }
  }
}
```

Allowed response:

```json theme={null}
{
  "decision": "allow",
  "decision_id": "dec_tool_result",
  "event_id": "evt_tool_result",
  "policy_id": "pol_123",
  "reasons": [],
  "run_id": "run_123",
  "tool": {
    "kind": "function",
    "name": "search_docs"
  }
}
```

If the decision is `block`, do not send the tool output back to the model.

## Output Checkpoint

Call `output` after the provider returns final text and before your app returns it to the user.

```json theme={null}
{
  "checkpoint_type": "output",
  "client": {
    "type": "api",
    "name": "custom-adapter",
    "version": "0.1.0"
  },
  "provider": {
    "name": "openai",
    "operation": "responses.create",
    "model": "gpt-5.4-mini",
    "streaming": false
  },
  "request_context": {
    "conversation_id": "conversation_123",
    "request_id": "request_456",
    "trace_id": "trace_789"
  },
  "output": {
    "content": {
      "value": "Here is the customer-safe answer."
    },
    "rewrite_attempt": 0
  }
}
```

Rewrite response:

```json theme={null}
{
  "decision": "rewrite",
  "decision_id": "dec_output",
  "event_id": "evt_output",
  "policy_id": "pol_123",
  "reasons": [
    {
      "code": "output_secret_disclosure_detected",
      "message": "Rewrite required."
    }
  ],
  "actions": {
    "rewrite": {
      "category": "secret_disclosure"
    }
  }
}
```

For `rewrite`, ask the provider for a safer answer, then call the output checkpoint again with `rewrite_attempt: 1`.

## Response Fields

| Field                      | Description                                                                   |
| -------------------------- | ----------------------------------------------------------------------------- |
| `decision`                 | Decision outcome for this checkpoint.                                         |
| `decision_id`              | Unique decision identifier.                                                   |
| `event_id`                 | Dashboard event identifier.                                                   |
| `policy_id`                | Policy that produced the decision.                                            |
| `reasons`                  | Machine-readable reason objects with `code` and `message`.                    |
| `run_id`                   | Tool-run identifier, present when a request starts or continues a tool chain. |
| `blocked_tools`            | Tool names blocked by a `restrict_tools` request decision.                    |
| `tool`                     | Tool identity for tool-call and tool-result decisions.                        |
| `actions.rewrite.category` | Rewrite category for output `rewrite` decisions.                              |

## Adapter Rules

* Do not call the provider when a request checkpoint returns `block`.
* Remove `blocked_tools` before provider execution when a request checkpoint returns `restrict_tools`.
* Do not execute a tool when a tool-call checkpoint returns `block`.
* Do not send tool output back to the model when a tool-result checkpoint returns `block`.
* Do not return final text to the user when an output checkpoint returns `block`.
* For output `rewrite`, generate a rewritten answer and check it again with `rewrite_attempt: 1`.