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

# Endpoint Types

> Guarded, direct, and grounded — the three endpoint families on Gloo AI, what each one runs around your request, and how to choose between them.

Gloo AI Responses and Completions endpoints belong to one of three families. All three share the same model catalog, authentication, metering and [rate limits](https://docs.gloo.com/api-reference/general/limits.md). What differs is **what runs around your request**.

| Family | What Gloo adds | Endpoints |
| :- | :- | :- |
| **Direct** | Nothing between your prompt and the provider | `/ai/v2/direct/responses`, `/ai/v2/direct/chat/completions`, `/ai/v2/direct/anthropic/v1/messages` |
| **Guarded** | [Guardrails](https://docs.gloo.com/ai-learning-center/gloo-ai-101/application-patterns.md#guardrails), output moderation, values-alignment; on Completions, [model families](https://docs.gloo.com/getting-started/glossary.md#model-family) and auto-routing | `/ai/v2/guarded/responses`, `/ai/v2/guarded/chat/completions` |
| **Grounded** | Retrieval over your own [uploaded content](https://docs.gloo.com/api-guides/upload-content.md) ([RAG](https://docs.gloo.com/ai-learning-center/gloo-ai-103/how-rag-actually-works.md)) | `/ai/v1/grounded/responses`, `/ai/v2/grounded/chat/completions` |

## Pricing at a glance

> [!TIP]
>
> Coming from another gateway? Direct endpoints cost what you would pay the model providers; guarded endpoints build in Gloo's safety and values alignment, priced at the model's rate plus 6.5%.

| Family | What you pay |
| :- | :- |
| **Direct** | The model's published rate, nothing added. |
| **Guarded** | The model's published rate plus 6.5% for guardrails, moderation, and values alignment. |
| **Grounded** | Grounded Responses bills the model's published rate with no separate charge for retrieval. Grounded Completions builds on guarded Completions and has the guarded platform price. |
| **Embeddings** | The model's published rate with nothing added. |
| **System One** | Per token at the model's list price, with no markup. |

Published rates are listed on [Supported Models](https://docs.gloo.com/api-guides/supported-models.md) and returned by `GET /platform/v2/models`, except System One's, which is in the [System One guide](https://docs.gloo.com/api-guides/system-one.md#pricing). See [Billing & Plans](https://docs.gloo.com/studio/billing.md) for how credits are drawn down.

Each generation family (Direct, Guarded and Grounded) comes in both request shapes, the OpenAI-compatible **Responses** format and the **Chat Completions** format, so you choose family and shape independently for generation requests. Embeddings and System One each have their own request shape.

## Guarded endpoints

Choose these when you want Gloo's safety and values alignment built in: input guardrails, output moderation and values-aligned (`tradition`) responses. On Guarded Completions you also get `model_family` selection and opt-in auto-routing, and Grounded Completions builds on Guarded Completions.

* [Responses](https://docs.gloo.com/api-guides/responses.md) (`POST /ai/v2/guarded/responses`) — the Responses format with Gloo's guardrails.
* [Completions](https://docs.gloo.com/api-guides/completions-v2.md) (`POST /ai/v2/guarded/chat/completions`) — fully supported, and the home of routing and `model_family`.

### When to choose guarded

Choose direct when you want the provider's model as-is and handle safety yourself; choose guarded when you want Gloo's safety and values alignment built in.

What guarded gives you:

* Input guardrails and output moderation: unsafe requests are refused (`403`) and unsafe replies replaced before your user sees them. A model's reasoning isn't moderated, so decide whether to show it; see [Reasoning is not moderated](https://docs.gloo.com/api-guides/reasoning.md#reasoning-is-not-moderated).
* Values-aligned responses through the `tradition` parameter.
* On [Completions](https://docs.gloo.com/api-guides/completions-v2.md), `model_family` selection and opt-in `auto_routing`.

Price: the model's published rate plus 6.5% for all of the above.

### Switch between direct and guarded

Keep the request body and change the path.

```bash Responses theme={null}
# Direct
curl https://platform.ai.gloo.com/ai/v2/direct/responses ...

# Guarded: same request, different path
curl https://platform.ai.gloo.com/ai/v2/guarded/responses ...
```

```bash Chat Completions theme={null}
# Direct
curl https://platform.ai.gloo.com/ai/v2/direct/chat/completions ...

# Guarded: same request, different path
curl https://platform.ai.gloo.com/ai/v2/guarded/chat/completions ...
```

If you use an OpenAI SDK, change the base URL from `https://platform.ai.gloo.com/ai/v2/direct` to `https://platform.ai.gloo.com/ai/v2/guarded`.

## Direct endpoints

Direct endpoints send your request straight to the model you name, with no guardrails, output moderation, values-alignment or routing in between. What you send is what the model sees; what the model returns is what you get. Direct endpoints have `/direct/` in their path.

Use them when your application owns its own safety and prompting end to end: an agent framework with its own moderation, a backend that composes prompts itself, or tooling that needs the model's own behavior, with nothing added to your request.

* [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md) (`POST /ai/v2/direct/responses`) — the Responses shape with nothing added, for apps that own their safety; multimodal.
* [Direct Completions](https://docs.gloo.com/api-guides/direct-completions.md) (`POST /ai/v2/direct/chat/completions`) — for existing Chat Completions tooling.
* [Anthropic Messages](https://docs.gloo.com/api-guides/anthropic-messages.md) (`POST /ai/v2/direct/anthropic/v1/messages`) — Anthropic's Messages API for Claude models, for code built on the Anthropic SDKs. It serves Claude only, has no provider failover, and returns an error for a retired model instead of serving its replacement.

### What runs, and what does not

Direct means direct about *content*, not a bypass of the platform:

**Still applies on direct Responses and Completions requests:**

* Authentication (Bearer [API key](https://docs.gloo.com/studio/manage-api-credentials.md)) and organization entitlement
* Usage metering and billing
* The Gloo model catalog — you address models by their `gloo-*` Model ID
* **Provider resiliency.** When the provider currently serving your model is failing or unhealthy, your request fails over to another provider that serves the same model, and a stream cut mid-answer can be continued on a fallback provider. The `model` you receive is the `model` you asked for: resiliency changes who serves it, never what you get. See [Provider Failover](https://docs.gloo.com/api-guides/provider-failover.md).
* Platform rate limits

**Deliberately not applied:**

* Input guardrails and output moderation
* Values-alignment (`tradition`)
* `model_family` selection and auto-routing — nothing picks a *different model* than the one you named (distinct from provider resiliency above, which only changes which provider serves that same model). The one exception is a deprecated model ID: once the catalog names a `replacement_model`, requests for it are served by that replacement. See [Model Lifecycle](https://docs.gloo.com/api-guides/model-lifecycle.md).
* Additions to your request — your messages go to the model verbatim

> [!WARNING]
>
> On direct endpoints, safety is your application's responsibility. Nothing screens the input before the model sees it, and nothing reviews the output before your user does. If any part of your traffic needs screening, route it through the guarded [Responses](https://docs.gloo.com/api-guides/responses.md) or [Completions](https://docs.gloo.com/api-guides/completions-v2.md) endpoints.

For what owning safety looks like in practice, see [Direct Endpoints and Untrusted Content](https://docs.gloo.com/best-practices/untrusted-content.md).

## Images and moderation

**Images and files you accept from users.** On guarded and direct endpoints alike, review images and PDFs from people you don't control with your own content checks before you send them. The model's maker may also decline an image under its own content policy ([Content Policy Refusals](https://docs.gloo.com/api-reference/general/errors.md#content-policy-refusals-direct-endpoints)). See [Images in Conversations](https://docs.gloo.com/best-practices/images-in-conversations.md#review-images-from-people-you-dont-control).

## Grounded endpoints

Grounded endpoints retrieve relevant passages from your uploaded content, add them as context before generation, and tell you whether the answer was grounded in your sources.

* [Grounded Responses](https://docs.gloo.com/api-guides/grounded-responses.md) (`POST /ai/v1/grounded/responses`) — grounding in the Responses shape.
* [Grounded Completions](https://docs.gloo.com/api-guides/grounded-completions.md) (`POST /ai/v2/grounded/chat/completions`) — grounding on Completions V2, with citation metadata and `tradition`.

## Which endpoint should I use?

| Use case | Endpoint |
| :- | :- |
| New integration; your app owns safety | [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md) |
| New integration; Gloo handles safety and values (`tradition`) | Guarded [Responses](https://docs.gloo.com/api-guides/responses.md) |
| AI Core (auto-routing) or AI Core Select (`model_family`), opt-in | Guarded [Completions](https://docs.gloo.com/api-guides/completions-v2.md) |
| Byte-faithful model behavior, nothing added to the request | [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md) |
| Existing Chat Completions tooling that should keep its request shape | [Direct Completions](https://docs.gloo.com/api-guides/direct-completions.md) or Guarded [Completions](https://docs.gloo.com/api-guides/completions-v2.md) |
| Existing code on the Anthropic SDK, calling Claude | [Anthropic Messages](https://docs.gloo.com/api-guides/anthropic-messages.md) |
| Vision (image input) or image generation | Either Responses endpoint — same request shape. See [Image generation tool](https://docs.gloo.com/api-guides/direct-responses.md#image-generation-tool) |
| Grounded / RAG answers over your own content, in the Responses shape (vision, `reasoning`, `response_format`, `certainty_threshold`) | [Grounded Responses](https://docs.gloo.com/api-guides/grounded-responses.md) |
| [Embedding](https://docs.gloo.com/ai-learning-center/gloo-ai-103/embeddings.md) vectors for your own search or [vector store](https://docs.gloo.com/ai-learning-center/gloo-ai-101/data-and-memory.md#semantic-search) | [Embeddings](https://docs.gloo.com/api-guides/embeddings.md) |
| Grounded answers in the Completions shape, with `include_citations`, `tradition`, `model_family`, or `auto_routing` | [Grounded Completions](https://docs.gloo.com/api-guides/grounded-completions.md) |
| A typed decision about your app's state (pick an option or score a statement), with probabilities | [System One](https://docs.gloo.com/api-guides/system-one.md) |

Not sure? Pick by who owns safety: [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md) if your app already does, guarded [Responses](https://docs.gloo.com/api-guides/responses.md) if Gloo should screen, moderate and align answers. Both take the same request body, so switching is a URL change.

## Choosing a model

Every endpoint takes a model ID, for example `gloo-openai-gpt-6-luna` or `gloo-anthropic-claude-sonnet-4.6`.

* **Pin a model for production (AI Select).** A pinned model ID gives predictable behavior. Auto-routing and `model_family` selection (Completions endpoints) can change the model between calls.
* **See the live catalog.** [Supported Models](https://docs.gloo.com/api-guides/supported-models.md) lists current model IDs, capabilities, and rates, rendered from `GET /platform/v2/models`.
* **Pick by capability and cost.** Check the catalog for each model's capabilities (such as vision or [tool calling](https://docs.gloo.com/ai-learning-center/gloo-ai-104/tools-and-mcp.md)) and rates, and test candidates with your own prompts.
* **Plan for deprecation.** Models can be deprecated and retired. See [Model lifecycle](https://docs.gloo.com/api-guides/model-lifecycle.md) for how notice works and how to migrate.

For choosing, pinning and moving between models in production, see [Choosing, Pinning and Updating Models](https://docs.gloo.com/best-practices/choosing-and-updating-models.md).

## Legacy endpoint aliases

The previous v2 paths remain as aliases for existing integrations. New integrations should use the canonical paths:

| Previous path | Canonical path |
| :- | :- |
| `/ai/v2/chat/completions` | `/ai/v2/guarded/chat/completions` |
| `/ai/v2/chat/completions/grounded` | `/ai/v2/grounded/chat/completions` |
| `/ai/v2/responses` | `/ai/v2/guarded/responses` |
| `/ai/v1/responses` (deprecated) | `/ai/v2/direct/responses` (see note below) |

The `/ai/v1/grounded/responses` endpoint is unchanged.

> [!NOTE]
>
> `/ai/v1/responses` is **not** an alias of the guarded endpoint. It runs without guardrails or output moderation, like the direct endpoint, so `/ai/v2/direct/responses` is the behavior-preserving move (a URL change only). Errors on `/ai/v2/direct/responses` follow the [direct endpoint error contract](https://docs.gloo.com/api-reference/general/errors.md#direct-endpoint-errors); `/ai/v1/responses` keeps its existing error responses. Use `/ai/v2/guarded/responses` for guardrails, moderation and `tradition`, at the guarded platform price; it refuses unsafe requests and replaces unsafe replies.

## Next steps

To build with each type step by step, follow [Build with Direct Responses](https://docs.gloo.com/tutorials/direct-responses.md) or [Using the Guarded Responses API](https://docs.gloo.com/tutorials/responses.md). [Building with Guarded Endpoints](https://docs.gloo.com/best-practices/guarded-endpoints.md) and [Direct Endpoints and Untrusted Content](https://docs.gloo.com/best-practices/untrusted-content.md) cover running each in production.

> [card] [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md)
>
> The Responses shape, straight to the model.

> [card] [Responses](https://docs.gloo.com/api-guides/responses.md)
>
> Responses with Gloo's guardrails, moderation and `tradition`.

> [card] [Completions V2](https://docs.gloo.com/api-guides/completions-v2.md)
>
> Guarded Completions with model families and auto-routing.

> [card] [Supported Models](https://docs.gloo.com/api-guides/supported-models.md)
>
> Model IDs, capabilities, and pricing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.