Create decision

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 for the end-to-end flow. If you are integrating OpenAI or Anthropic directly, use the provider SDK wrappers instead.

Endpoint

POST https://api.averta.io/v1/decide

Authentication

Authorization: Bearer <averta-api-key>
Content-Type: application/json

The API key must have a policy 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`.

{
  "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.

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.

{
  "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.

{
  "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.

{
  "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:

{
  "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.

{
  "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:

{
  "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.

{
  "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:

{
  "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.

​Endpoint

​Authentication

​Checkpoint Model

​Shared Body Fields

​Request Checkpoint

​Media on Request

​Tool-call Checkpoint

​Tool-result Checkpoint

​Output Checkpoint

​Response Fields

​Adapter Rules