# Telnyx Agent Tools: Agent Gateway — Full Documentation
> Complete page content for Agent Gateway (Agent Tools section) of the Telnyx developer docs (https://developers.telnyx.com).
> This file: https://developers.telnyx.com/docs/development/llms/agent-tools-agent-gateway-llms-full-txt · Root index: https://developers.telnyx.com/llms.txt

## Get Started

### Overview

> Source: https://developers.telnyx.com/docs/agent-gateway.md

**Beta.** Rows marked Preview or Planned arrive in later releases.

**On the data plane**, an Agent Gateway instance sits inline between agents and their [*targets*](#targets), [*on the user's Network*](#virtual-private-cloud), off the internet. It [*authenticates to each target*](#outbound-authentication) with credentials it holds, and [*authenticates every request*](#inbound-authentication) an agent sends to its `gateway_url`.

**On the control plane**, at `api.telnyx.com`, the user sets each agent's [*authorization and policy*](#authorization-and-policy), [*controls its traffic*](#traffic-control), and [*audits its requests*](#audit-and-observability).

## Targets

| Target | What It Does | Availability |
| --- | --- | --- |
| [Models](/docs/agent-gateway/targets/models) | One OpenAI-compatible endpoint for every model an agent uses. | Beta |
| [Tools](/docs/agent-gateway/targets/tools) | Tools from Model Context Protocol (MCP) servers and REST APIs, served to the agent through one MCP endpoint. With [tool search](/docs/agent-gateway/targets/tools#tool-search), the agent loads only the tools it needs. | Beta |
| Agents | Requests to other agents over agent-to-agent (A2A). | Planned |

## Virtual Private Cloud

| Component | Where It Runs | Availability |
| --- | --- | --- |
| [Agents](/docs/agent-gateway/vpc) | Edge Compute functions on the user's [*Network*](/docs/network/overview). Each sends its requests to `gateway_url`. | Preview |
| [Forwarding peer](/docs/agent-gateway/vpc) | A WireGuard peer inside the user's network that forwards the instance's requests to its subnets. | Preview |
| [Tunnel hosts](/docs/agent-gateway/vpc) | Hosts inside the user's network that run a [Tunnel](/docs/network/tunnel) to Telnyx. | Preview |

## Outbound Authentication

Outbound authentication is not a resource of its own. Each MCP server and API holds its method and credentials in its [`auth`](/docs/agent-gateway/targets/tools#outbound-authentication).

| Method | How It Works | Availability |
| --- | --- | --- |
| [API keys](/docs/agent-gateway/outbound/api-keys) | The gateway sends a static API key, bearer token, or password with every request to the server. | Beta |
| [OAuth client credentials](/docs/agent-gateway/outbound/oauth-client-credentials) | The gateway trades a client ID and secret for a short-lived access token from the server's OAuth provider, and renews it before it expires. | Beta |
| OAuth authorization code | Each user authorizes the gateway once, and the gateway sends the server that user's own token. | Planned |
| OAuth token exchange | The gateway exchanges the agent's token for one issued for the server, on the user's behalf. | Planned |
| [Token passthrough](/docs/agent-gateway/outbound/token-passthrough) | The gateway forwards the agent's own token to the server unchanged. | Beta |
| [AWS Signature Version 4](/docs/agent-gateway/outbound/aws-signature-v4) | The gateway signs each request to a server on AWS with stored AWS keys or an assumed role. | Beta |

## Inbound Authentication

| Method | How It Works | Availability |
| --- | --- | --- |
| [Keys](/docs/agent-gateway/authentication/keys) | The gateway issues a key to each agent or team, and the agent presents it on every request. | Beta |
| Identity provider tokens | The agent authenticates with a token from the user's own identity provider over OpenID Connect (OIDC), such as Okta or Microsoft Entra ID. The token's claims identify the agent and its groups, and the gateway itself issues no keys. | Planned |

## Authorization and Policy

| Control | How It Works | Availability |
| --- | --- | --- |
| [Allow lists](/docs/agent-gateway/authorization/allow-lists) | Each key or team names the models it may use. A model outside its list is refused. | Beta |
| [Tool permissions](/docs/agent-gateway/authorization/tool-permissions) | Each key or team names the MCP servers and tools it may use, and the agents it may reach. The agent sees only those tools. | Beta |
| [Guardrails](/docs/agent-gateway/authorization/guardrails) | Checks that run before and after each request to a model or tool, such as masking personal data or blocking keywords. They run on every request or on the requests that name them. | Beta |
| [Policies](/docs/agent-gateway/authorization/policies) | Named sets of guardrails that build on a base policy. They apply to every request, to some models, or to the requests that name them. | Beta |

## Traffic Control

| Control | How It Works | Availability |
| --- | --- | --- |
| [Budgets and rate limits](/docs/agent-gateway/traffic/budgets-and-rate-limits) | A spend cap in USD, and requests and tokens per minute, per key and per team. A request past a limit is refused. | Beta |
| [Routing and fallbacks](/docs/agent-gateway/traffic/routing-and-fallbacks) | Retries, timeouts, and fallbacks to another model when one fails. | Beta |
| Caching | Repeated requests are answered from a cache. | Planned |

## Audit and Observability

| Record | What It Holds | Availability |
| --- | --- | --- |
| [Spend logs](/docs/agent-gateway/observability/spend-logs) | Every request, with its key, team, model, tokens, cost, status, and duration. | Beta |
| Traces and metrics | A trace per request in OpenTelemetry, and request, error, and latency metrics per key, team, and model. | Planned |
| Log export | Request logs sent to the user's own observability tools, such as an OpenTelemetry collector, Langfuse, Datadog, or S3. | Planned |
| Audit logs | Who created, changed, or deleted a key, team, or model, and when. | Planned |

---

### Quick Start

> Source: https://developers.telnyx.com/docs/agent-gateway/quick-start.md

## Prerequisites

- A WireGuard Interface on a [*Network*](/docs/network/overview), as in the [WireGuard Interface Quick Start](/docs/network/wireguard-interfaces/quick-start). This page uses the interface `c788eb40-a4c0-4bf5-8f84-976027960f8e`.
- An Edge Compute function and the `telnyx-edge` CLI, as in the [Edge Compute Quick Start](/docs/edge-compute/quickstart).

An Agent Gateway instance sits on the user's [*Network*](/docs/network/overview). This page creates one, issues a key, and connects an agent to it.

New instances currently cannot finish provisioning: they move from `pending` to `failed` at their database migration (AIPLAT-1702), so a newly created instance does not reach `ready`. The steps on this page ran on instances that provisioned before this regression.

## Create the Agent Gateway

Send [`POST /v2/agent_gateways`](/api-reference/agent-gateways/create-an-agent-gateway) with the WireGuard Interface's `id`:

```json
{
  "name": "support-gw",
  "wireguard_interface_id": "c788eb40-a4c0-4bf5-8f84-976027960f8e"
}
```

The response returns the instance `pending`, with no `gateway_url` yet. `network_id` is the WireGuard Interface's *Network*.

```json
{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "name": "support-gw",
    "status": "pending",
    "gateway_url": null,
    "wireguard_interface_id": "c788eb40-a4c0-4bf5-8f84-976027960f8e",
    "network_id": "7ade8c3c-95a7-447b-92f2-c829f760159c",
    ...
  }
}
```

## Wait for the Gateway

Poll [`GET /v2/agent_gateways/{id}`](/api-reference/agent-gateways/retrieve-an-agent-gateway) until `status` is `ready`. The instance joins the WireGuard Interface as a peer named `agw-32ce035d-3165-4031-b1a7-a7c0c259590a`, which puts the interface in `provisioning` again. The instance is `ready` once the interface is `provisioned` and the instance answers through the tunnel. Here that took 172 seconds. `gateway_url` is its address on the interface:

```json
{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "status": "ready",
    "gateway_url": "http://172.27.0.4:4000",
    ...
  }
}
```

## Issue a Key

The instance refuses a request without a [key](/docs/agent-gateway/authentication/keys). Send [`POST /v2/agent_gateways/{id}/keys`](/api-reference/agent-gateway-keys/create-a-key) with a name for the agent that holds it:

```json
{
  "name": "support-agent"
}
```

The response carries the key's value in `key`, and no later response returns it:

```json
{
  "data": {
    "id": "9b1f1703ade70a9e35be9ac96d439ce3bc8e68ca7fd0ae5fa4d847977d23f7bc",
    "key": "sk-EXAMPLE-KEY-VALUE",
    "name": "support-agent",
    "models": [],
    "blocked": false,
    ...
  }
}
```

## Connect an Agent

An agent on Edge Compute reaches the instance through a [network binding](/docs/edge-compute/runtime/bindings/network) to the instance's WireGuard Interface. In the function's `func.toml`, bind the interface and set the instance's `gateway_url`:

```toml func.toml
[network.PRIVATE_NET]
id = "c788eb40-a4c0-4bf5-8f84-976027960f8e"

[env_vars]
GATEWAY_URL = "http://172.27.0.4:4000"
```

Store the key from [Issue a Key](#issue-a-key) as a secret:

```bash Workstation
telnyx-edge secrets add AGENT_GATEWAY_KEY "$AGENT_GATEWAY_KEY"
```

The function sends a chat completion to `gateway_url` through the binding, with the key:

```ts index.ts
import * as http from "node:http";
import { env } from "@telnyx/edge-runtime";

const { GATEWAY_URL, AGENT_GATEWAY_KEY } = process.env;

const server = http.createServer(async (req, res) => {
  if (req.url === "/health" || req.url?.startsWith("/health/")) {
    res.writeHead(200); res.end(); return;
  }
  const response = await env.PRIVATE_NET.fetch(`${GATEWAY_URL}/v1/chat/completions`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${AGENT_GATEWAY_KEY}` },
    body: JSON.stringify({
      model: "GLM-5.3-Flash",
      messages: [{ role: "user", content: "Say hello in five words." }],
    }),
  });
  const completion = await response.json();
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ answer: completion.choices[0].message.content }));
});

server.listen(process.env.PORT || 8080);
```

Generate the binding's types, and ship the function:

```bash Workstation
telnyx-edge types
telnyx-edge ship
```

Send the function a request:

```bash Workstation
curl https://acme-agent-6a01e98a-b.telnyxcompute.com
```

```json Output
{"answer":"Hello, nice to meet you!"}
```

The instance's [spend logs](/docs/agent-gateway/observability/spend-logs) list the request under the key `support-agent`.

## Delete the Agent Gateway

[`DELETE /v2/agent_gateways/{id}`](/api-reference/agent-gateways/delete-an-agent-gateway) returns the instance `deleting`. The gateway stops answering at once, and seconds later `GET /v2/agent_gateways/{id}` returns `404`.

```json
{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "status": "deleting",
    ...
  }
}
```

---

### Pricing

> Source: https://developers.telnyx.com/docs/agent-gateway/pricing.md

An Agent Gateway bills on three meters:

| Meter | Unit | Rate |
| --- | --- | --- |
| Instance | Per instance, per month | $50 |
| Requests | Per 1,000 requests | A fixed rate |
| Tokens | Per token | The [Telnyx Inference](/docs/inference/models/pricing) price of the model, with no markup |

## Requests

Every request the instance records counts toward the request meter, whether it goes to a model, a tool, or an agent. The instance's [spend logs](/docs/agent-gateway/observability/spend-logs) list each one.

## Tokens

Model tokens cost the same through an instance as through [Telnyx Inference](/docs/inference/models/pricing) directly. A model request counts once on the request meter, and its tokens bill at the model's price.

---

## Targets

### Overview

> Source: https://developers.telnyx.com/docs/agent-gateway/targets.md

Targets give an instance its capabilities. Each kind has its own endpoint:

- [Models](/docs/agent-gateway/targets/models) share one OpenAI-compatible API at `{gateway_url}/v1`. The request's `model` selects the model.
- [Tools](/docs/agent-gateway/targets/tools) from every MCP server and REST API added to the instance are combined into one MCP server at `{gateway_url}/mcp`.
- Agents Planned each have a path at `{gateway_url}/a2a/{agent}`, over agent-to-agent (A2A), and the instance forwards their requests.

The instance authenticates to each MCP server and API by the [outbound authentication](/docs/agent-gateway#outbound-authentication) method set on it. The models are Telnyx-hosted and need no credentials.

[Allow lists](/docs/agent-gateway/authorization/allow-lists) limit the models a key may use, and [tool permissions](/docs/agent-gateway/authorization/tool-permissions) limit its tools and agents.

---

### Models

> Source: https://developers.telnyx.com/docs/agent-gateway/targets/models.md

An instance serves an OpenAI-compatible API at its `gateway_url`, and the Anthropic Messages API beside it. An OpenAI or Anthropic client works against it unchanged:

| Path | What It Does |
| --- | --- |
| `GET {gateway_url}/v1/models` | Lists the models the instance serves. |
| `POST {gateway_url}/v1/chat/completions` | Chat completions, with streaming and tool use. |
| `POST {gateway_url}/v1/responses` | Responses, in the OpenAI Responses API format. |
| `POST {gateway_url}/v1/messages` | Messages, in the Anthropic Messages API format. |

**Beta.** Every instance serves the models below, and models from other providers cannot be added.

## Set Up

An instance serves models from [Telnyx Inference](/docs/inference/models) as soon as it is `ready`, with nothing to add, and [`GET /v2/agent_gateways/{id}/models`](/api-reference/agent-gateways/list-an-agent-gateways-models) lists them. Requests name a model by the instance's name for it, which differs from its Telnyx Inference model ID:

| Model | Telnyx Inference Model | Reasoning |
| --- | --- | --- |
| `GLM-5.3` | `zai-org/GLM-5.3` | Yes |
| `GLM-5.3-Flash` | `zai-org/GLM-5.3-Flash` | Yes |
| `DeepSeek-V4.1-Flash` | `deepseek-ai/DeepSeek-V4.1-Flash` | No |
| `Qwen3.8-27B` | `Qwen/Qwen3.8-27B` | Yes, at low effort |
| `Qwen3.8-27B-nothink` | `Qwen/Qwen3.8-27B` | No |

A model has no settings of its own. Each key and team has:

- An [allow list](/docs/agent-gateway/authorization/allow-lists) of the models it may use.
- A [budget and rate limits](/docs/agent-gateway/traffic/budgets-and-rate-limits) for its requests.

A request sets its own [retries, timeout, and fallbacks](/docs/agent-gateway/traffic/routing-and-fallbacks).

## Use

A request comes from a host on the instance's [*Network*](/docs/network/overview), goes to `gateway_url`, and carries a [key](/docs/agent-gateway/authentication/keys) as a bearer token. The commands below read both from the host's environment, as `GATEWAY_URL` and `AGW_KEY`.

### List the Models

```bash Host
curl "$GATEWAY_URL/v1/models" \
  -H "Authorization: Bearer $AGW_KEY"
```

```json Output
{
  "data": [
    { "id": "GLM-5.3", "object": "model", "created": 1677610602, "owned_by": "openai" },
    { "id": "GLM-5.3-Flash", "object": "model", "created": 1677610602, "owned_by": "openai" },
    { "id": "DeepSeek-V4.1-Flash", "object": "model", "created": 1677610602, "owned_by": "openai" },
    { "id": "Qwen3.8-27B", "object": "model", "created": 1677610602, "owned_by": "openai" },
    { "id": "Qwen3.8-27B-nothink", "object": "model", "created": 1677610602, "owned_by": "openai" }
  ],
  "object": "list"
}
```

### Send a Chat Completion

`POST {gateway_url}/v1/chat/completions` takes an OpenAI chat completion request:

```bash Host
curl "$GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AGW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.3-Flash",
    "messages": [
      { "role": "user", "content": "In one sentence, what does a gateway do?" }
    ]
  }'
```

The instance answers in the OpenAI chat completion format:

```json Output
{
  "id": "chatcmpl-4ccb13b2-d225-4764-900e-76b44502de2e",
  "model": "GLM-5.3-Flash",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A gateway is a network device or node that connects two networks using different protocols, translating and routing data between them so they can communicate—essentially serving as an entry and exit point between networks.",
        "reasoning_content": "The user is asking a simple question about what a gateway does, and they want ...",
        ...
      }
    }
  ],
  "usage": {
    "completion_tokens": 278,
    "prompt_tokens": 22,
    "total_tokens": 300,
    "completion_tokens_details": { "reasoning_tokens": 240 },
    ...
  },
  ...
}
```

The models behave as they do on Telnyx Inference, including [reasoning](/docs/inference/getting-started), [streaming](/docs/inference/getting-started#streaming), and [function calling](/docs/inference/functions).

---

### Tools

> Source: https://developers.telnyx.com/docs/agent-gateway/targets/tools.md

An instance combines the tools of every Model Context Protocol (MCP) server and REST API added to it into one MCP server at `{gateway_url}/mcp`. The agent connects one MCP client to the gateway instead of one to each server. The gateway routes each tool request to the server or API that owns the tool, and authenticates to it with that target's own credentials. It serves the MCP servers' prompts and resources the same way.

## Set Up

### MCP Servers

[`POST /v2/agent_gateways/{id}/mcp_servers`](/api-reference/agent-gateway-mcp-servers/add-an-mcp-server) adds a server by its MCP endpoint. This one runs inside the user's network, behind [tunnel hosts](/docs/agent-gateway/vpc) Preview, and the gateway sends it an [API key](/docs/agent-gateway/outbound/api-keys):

```json
{
  "name": "orders",
  "url": "http://10.40.3.7:9000/mcp",
  "auth": { "type": "api_key", "value": "example-orders-key" }
}
```

### APIs

[`POST /v2/agent_gateways/{id}/apis`](/api-reference/agent-gateway-apis/add-an-api) adds a REST API by the URL of its OpenAPI description, in JSON. Each operation in the description becomes one tool. When the agent invokes the tool, the gateway sends the operation's HTTP request to the API itself, with no MCP server in between. This public API needs no `auth`:

```json
{
  "name": "petstore",
  "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
  "base_url": "https://petstore3.swagger.io/api/v3"
}
```

The gateway reads OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0. Without a `base_url`, it takes the first entry in the description's `servers`.

The gateway reaches an MCP server or API across the instance's [*Network*](/docs/network/overview), so either can stay off the internet.

### Outbound Authentication

Outbound authentication is not a resource of its own. Each MCP server and API holds its method and the credentials themselves in `auth`, and the gateway authenticates to it with them on every request. Responses return only `auth.type`.

`auth.type` picks the method:

| `auth.type` | Method |
| --- | --- |
| `api_key`, `bearer_token`, `basic`, `token`, `authorization` | [API keys](/docs/agent-gateway/outbound/api-keys) |
| `oauth_client_credentials` | [OAuth client credentials](/docs/agent-gateway/outbound/oauth-client-credentials) |
| `passthrough` | [Token passthrough](/docs/agent-gateway/outbound/token-passthrough) |
| `aws_sigv4` | [AWS Signature Version 4](/docs/agent-gateway/outbound/aws-signature-v4), for MCP servers only |
| `none` | No credential, as when `auth` is left out |

OAuth authorization code and OAuth token exchange are Planned.

### Settings

Each MCP server and API has:

- A `name`, which prefixes its tools. A name holds up to 100 letters, digits, `_`, and `.`, and is unique on the instance, regardless of case, across MCP servers and APIs.
- Its address. An MCP server has a `url` and a `transport`, Streamable HTTP (`http`, the default) or Server-Sent Events (`sse`). An API has a `spec_url` and a `base_url`.
- An `auth`, its [outbound authentication](#outbound-authentication) method.
- `tools`, the tools it exposes to every key, by name. `[]` exposes every tool.
- `static_headers`, sent on every request, and `forwarded_headers`, copied from the agent's request by name.
- `open_to_every_key`, which opens it to every key on the instance. Otherwise, only the keys [granted](/docs/agent-gateway/authorization/tool-permissions) it may use it.

Only the `name` and the `url` or `spec_url` are required.

### Operations as Tools

The gateway makes one tool from each `get`, `post`, `put`, `patch`, and `delete` operation in an API's description:

| Tool Part | Taken From |
| --- | --- |
| Name | The `operationId`, lowercased, with spaces as underscores, after the API's name and a hyphen. An operation without an `operationId` is named from its method and path. |
| Description | The operation's `summary`, or its `description`, or its method and path. |
| Arguments | Each path and query parameter, and a JSON request body as one `body` argument with the body's top-level properties. |

The operation `findPetsByStatus` on the API `petstore` is the tool `petstore-findpetsbystatus`.

Header and cookie parameters are not sent to the API. A request body defined by a `$ref` reaches the agent as an object with no properties.

### Changes

[`PATCH /v2/agent_gateways/{id}/mcp_servers/{server_id}`](/api-reference/agent-gateway-mcp-servers/update-an-mcp-server) changes a server's settings, and [`PATCH /v2/agent_gateways/{id}/apis/{api_id}`](/api-reference/agent-gateway-apis/update-an-api) changes an API's. An update replaces `auth` whole, and `{"type": "none"}` removes the credential. `DELETE` on the same paths removes the server or API.

## Use

### Connections

Any MCP client connects to `{gateway_url}/mcp` over [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http), at protocol versions `2024-11-05` through `2025-11-25`. The client presents its [key](/docs/agent-gateway/authentication/keys) as a bearer token, `Authorization: Bearer <key>`.

### Tool Names

Every tool's name starts with its server's or API's name and a hyphen. The tool `get_order` on the server `orders` is `orders-get_order`:

```json Output
{
  "tools": [
    { "name": "orders-create_ticket", "description": "Open a support ticket with a subject.", ... },
    { "name": "orders-get_order", "description": "Look up an order by its ID.", ... }
  ]
}
```

Prompts carry the same prefix, so names stay unique across servers.

### Server Scoping

`{gateway_url}/mcp/{server}` serves only that server's tools, still prefixed. A comma-separated list, such as `{gateway_url}/mcp/github,jira`, serves several. The `x-mcp-servers` header narrows `{gateway_url}/mcp` the same way, with a comma-separated list of server names.

A path or header narrows what the agent sees. It never adds a server the agent has no [permission](/docs/agent-gateway/authorization/tool-permissions) to use.

### Results

An API tool's result is the API's response body when the response is in the `2xx` range. Any other response is an error result that names the HTTP status, without the API's response body:

```text Output
Error: upstream returned HTTP 404
```

### Tool Search

With tool search Preview on for a key, `tools/list` returns four search tools in place of the full catalog. Two of them reach MCP tools:

- `mcp_tool_search` takes a `query` and an optional `top_k`, 5 by default. It returns the matching tools, each with its name, description, and input schema.
- `mcp_tool_call` takes a `tool_name` and its `arguments`, and invokes that tool.

The other two, `agent_search` and `skill_search`, find agents and skills by query.

Matching is by keyword. A tool scores a point for each word of the query found in its name or description, and a tool that scores nothing is left out. With an embedding model set on the instance, matching is by meaning instead.

Search covers only the tools the key may use, and `mcp_tool_call` applies the same [tool permissions](/docs/agent-gateway/authorization/tool-permissions) as a direct request.

---

## Virtual Private Cloud

### Overview

> Source: https://developers.telnyx.com/docs/agent-gateway/vpc.md

**Preview.** Not available yet.

An agent on the user's [*Network*](/docs/network/overview) reaches services inside the user's network, such as MCP servers and APIs, through an Agent Gateway instance. No service needs a public address. These are the pieces that build it:

| Artifact | What It Does | Where |
| --- | --- | --- |
| [*Network*](/docs/network/overview) | Holds the instance, the agents, and the routes to the user's network. | Telnyx |
| [WireGuard Interface](/docs/network/wireguard-interfaces) | Attaches the instance and the agents to the *Network*. | Telnyx |
| [Agent Gateway instance](/docs/agent-gateway/quick-start#create-the-agent-gateway) | Takes every request from the agents at its `gateway_url`, and reaches the services for them. | Telnyx |
| [Edge Compute function](/docs/edge-compute/overview) with a [network binding](/docs/edge-compute/runtime/bindings/network) | Runs an agent on the *Network*, public or private. | Telnyx |
| [Route](/docs/network/routes) | Sends a CIDR of the user's network to a forwarding peer or to a tunnel. | Telnyx |
| Forwarding peer, a [WireGuard peer](/docs/network/wireguard-interfaces/quick-start) | Forwards traffic from the *Network* to the subnets behind it. | The user's network |
| Tunnel hosts, running a [Tunnel](/docs/network/tunnel) | Connect out to Telnyx, with no change to the user's router or firewall, and carry traffic to the subnets they reach. | The user's network |

A forwarding peer and tunnel hosts are two ways into the same subnets. Either one carries the instance's requests to the services.

---

## Outbound Authentication

### API Keys

> Source: https://developers.telnyx.com/docs/agent-gateway/outbound/api-keys.md

An API key is a static credential set once on an MCP server or API on the instance. The gateway adds it to every request it sends there. The agent never sends or receives it.

## Key Types

The server's `auth` sets the type, and `value` holds the key itself:

```json
{
  "type": "api_key",
  "value": "example-orders-key"
}
```

| Type | What the Server Receives |
| --- | --- |
| `api_key` | `X-API-Key: <key>` |
| `bearer_token` | `Authorization: Bearer <token>` |
| `basic` | `Authorization: Basic <base64 of user:password>`, from a `value` of `user:password` |
| `token` | `Authorization: token <token>` |
| `authorization` | `Authorization: <value>`, exactly as stored |

`header` sends the key in a header of another name in place of `Authorization` or `X-API-Key`. An [API added as tools](/docs/agent-gateway/targets/tools#apis) receives an `api_key` as both `X-API-Key: <key>` and `Authorization: ApiKey <key>`.

## Static Headers

Static headers go to the server on every request, alongside the key. A static header replaces any header of the same name from another source.

## Per-User Keys

A server can take one key per user Preview instead of one key for everyone. Each user stores a key once, and the gateway sends it on that user's requests in the server's key format, such as `Authorization: Bearer <key>`.

## Storage

The gateway encrypts every credential it stores, including OAuth client secrets and users' tokens. No response returns them, including to the account that stored them, and a server shows only its `auth.type`.

---

### OAuth Client Credentials

> Source: https://developers.telnyx.com/docs/agent-gateway/outbound/oauth-client-credentials.md

With OAuth client credentials, the gateway authenticates to an MCP server or API as itself. It gets an access token from the server's OAuth provider with the `client_credentials` grant, and sends it as `Authorization: Bearer <token>` on every request. Every agent reaches the server under that one identity.

## Settings

The server's `auth` names the provider's token endpoint and the gateway's client:

```json
{
  "type": "oauth_client_credentials",
  "token_url": "https://auth.example.com/oauth/token",
  "client_id": "example-client",
  "client_secret": "example-client-secret",
  "scopes": ["orders.read"],
  "audience": "orders-api"
}
```

- `token_url` is the provider's token endpoint.
- `client_id` and `client_secret` identify the gateway. `credentials_in` sends them in the token request's body (`body`, the default) or as HTTP Basic authentication (`basic`).
- `scopes`, `audience`, and `resource` are optional, and go in the token request.

## Token Lifetime

The gateway keeps the token and gets a new one a minute before it expires. A token without an expiry is kept for 5 minutes. When the server answers `401`, the gateway gets a new token and retries the request once.

---

### Token Passthrough

> Source: https://developers.telnyx.com/docs/agent-gateway/outbound/token-passthrough.md

Some MCP servers authenticate the end user themselves. A passthrough server, with an `auth` of `{"type": "passthrough"}`, receives the agent's `Authorization` header unchanged. The gateway does not inspect the token, and the server decides whether to accept it. When the server refuses the token, the agent gets an error result, `Error: upstream authentication required (HTTP 401)`, and `tools/list` leaves out the server's tools.

The agent names the passthrough servers in the `x-mcp-servers` header. The gateway does not authenticate a request whose servers are all passthrough servers, and leaves it out of spend and rate limits.

## Per-Request Headers

A request can carry a header for one server in `x-mcp-{server}-{header}`. The gateway sends it to that server as `{header}`, with the value as given. With a key, the agent authenticates to the gateway in `Authorization` and sends the server's token alongside:

```text
Authorization: Bearer <key>
x-mcp-github-authorization: Bearer <GitHub token>
```

The server `github` receives `Authorization: Bearer <GitHub token>`. A server can also take named headers from the agent's request as they are, in its `forwarded_headers`.

---

### AWS Signature Version 4

> Source: https://developers.telnyx.com/docs/agent-gateway/outbound/aws-signature-v4.md

For an MCP server on AWS, such as one hosted on Amazon Bedrock AgentCore, the gateway signs each request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Signing applies to MCP servers, not to [APIs added as tools](/docs/agent-gateway/targets/tools#apis).

## Settings

The server's `auth` names the region, and optionally the service and credentials:

```json
{
  "type": "aws_sigv4",
  "region": "us-east-1",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key": "example-secret-access-key"
}
```

- `region` is the AWS region to sign for.
- `service` is the service to sign for, `bedrock-agentcore` unless set.
- `access_key_id` and `secret_access_key`, with an optional `session_token`, are AWS keys. `role_name` is the ARN of a role for the gateway to assume instead.

---

## Inbound Authentication

### Keys

> Source: https://developers.telnyx.com/docs/agent-gateway/authentication/keys.md

A key is a credential for one instance's API. The gateway issues a key to an agent or a team, and the agent presents it on every request. Telnyx holds the instance's master key and never shows it.

## Issuance

Send [`POST /v2/agent_gateways/{id}/keys`](/api-reference/agent-gateway-keys/create-a-key). Every field is optional, and a key's `name` is unique on the instance. A key with a `team_id` belongs to that [team](/docs/agent-gateway/authorization/allow-lists#teams) and shares its [allow list](/docs/agent-gateway/authorization/allow-lists), [budget, and rate limits](/docs/agent-gateway/traffic/budgets-and-rate-limits).

```json
{
  "name": "support-agent",
  "team_id": "d7b21324-a2bf-406c-ba49-c6ec4d23d476",
  "expires_in": "30d"
}
```

The response carries the key's value in `key`. Telnyx returns it in this response only. The key's `id` is a hash the instance stores in place of the value, and the API takes the `id` to change or revoke the key.

```json
{
  "data": {
    "id": "f739ad190d29e2a5e658c3a486111953e6c18d746fd04374962ab150aae17757",
    "key": "sk-EXAMPLE-KEY-VALUE",
    "name": "support-agent",
    "team_id": "d7b21324-a2bf-406c-ba49-c6ec4d23d476",
    "expires_at": "2026-11-25T16:05:09.835451Z",
    "blocked": false,
    ...
  }
}
```

## Presentation

The agent sends the key to the instance as a bearer token, `Authorization: Bearer <key>`, on every request. The instance refuses a request without a valid key.

## Expiry

`expires_in` sets how long the key works, as a number and a unit (`s`, `m`, `h`, or `d`), such as `30d`. The response shows the resulting `expires_at`. Setting `expires_in` with [`PATCH /v2/agent_gateways/{id}/keys/{key_id}`](/api-reference/agent-gateway-keys/update-a-key) counts from the time of the update.

## Blocking and Revocation

`"blocked": true` makes the instance refuse the key. The key keeps its settings and spend, and `"blocked": false` lets it through again.

[`DELETE /v2/agent_gateways/{id}/keys/{key_id}`](/api-reference/agent-gateway-keys/delete-a-key) revokes the key and returns it without its value.

Every change to a key reaches the instance within a minute, including a block and a revocation.

---

## Authorization and Policy

### Allow Lists

> Source: https://developers.telnyx.com/docs/agent-gateway/authorization/allow-lists.md

Each [key](/docs/agent-gateway/authentication/keys) or team names the models it may use in `models`. A model outside the list is refused with `403`, and `GET {gateway_url}/v1/models` lists only the models the key may use. A key or team without a list may use every model the instance serves.

## Teams

A team is a model list, a budget, and rate limits that its keys share. Send [`POST /v2/agent_gateways/{id}/teams`](/api-reference/agent-gateway-teams/create-a-team). `name` is required, and need not be unique. The team's `id` identifies it.

```json
{
  "name": "support",
  "models": ["GLM-5.3-Flash", "Qwen3.8-27B-nothink"]
}
```

A key joins the team with the team's `id` in its `team_id`.

## List Changes

[`PATCH /v2/agent_gateways/{id}/keys/{key_id}`](/api-reference/agent-gateway-keys/update-a-key) and [`PATCH /v2/agent_gateways/{id}/teams/{team_id}`](/api-reference/agent-gateway-teams/update-a-team) replace `models` without reissuing anything. `"models": []` removes the list, and a key in a team then uses the team's list.

```json
{
  "models": ["GLM-5.3-Flash"]
}
```

## Blocked Teams

`"blocked": true` on a team makes the instance refuse every key in it. The team keeps its settings and spend, and `"blocked": false` lets its keys through again. Like every change to a team, the block reaches its keys within a minute.

## Team Deletion

[`DELETE /v2/agent_gateways/{id}/teams/{team_id}`](/api-reference/agent-gateway-teams/delete-a-team) deletes a team that has no keys.

---

### Tool Permissions

> Source: https://developers.telnyx.com/docs/agent-gateway/authorization/tool-permissions.md

Each [key](/docs/agent-gateway/authentication/keys) or [team](/docs/agent-gateway/authorization/allow-lists#teams) names the MCP servers and tools it may use, and the agents it may reach. The gateway hides everything else from the agent and refuses requests for it.

## MCP Servers

A key reaches the [MCP servers and APIs](/docs/agent-gateway/targets/tools) granted to it or to its team, and the servers open to every key. When both the key and its team have a grant, the key reaches only the servers and tools in both. A key with no grant from either reaches only the servers open to every key.

[`PUT /v2/agent_gateways/{id}/keys/{key_id}/tool_permissions`](/api-reference/agent-gateway-tool-permissions/set-a-keys-tool-permissions) replaces a key's grant, and the same path under a team replaces the team's. Each entry names a server by its `id`:

```json
{
  "servers": [
    { "id": "88d5a97b-4080-4855-8bac-a39811b1dc24", "tools": ["get_order"] }
  ]
}
```

`tools: []` grants every tool the server exposes, and `servers: []` grants none.

`tools/list` returns the tools of the servers the key reaches, and no others. A changed grant reaches the instance within a minute.

## Tools

Within a server, a grant can name some of its tools. A server can also expose only some of its tools to every key, in its own `tools`.

The gateway refuses a `tools/call` request for a tool outside these limits, and the request never reaches the server. The agent gets an error result in place of the tool's result.

## Agents

A key or team can name the agents Planned it may reach. A key reaches every agent on the instance until it or its team names some. When both name agents, the key reaches only the agents in both. The gateway refuses requests to any other agent.

---

### Guardrails

> Source: https://developers.telnyx.com/docs/agent-gateway/authorization/guardrails.md

A guardrail checks a request or a response, and blocks it, masks part of it, or only logs what it found. Guardrails run on model requests and on MCP tool requests.

[`POST /v2/agent_gateways/{id}/guardrails`](/api-reference/agent-gateway-guardrails/add-a-guardrail) adds one. This guardrail masks Social Security numbers and email addresses before a request reaches the model:

```json
{
  "name": "mask-pii",
  "modes": ["before_request"],
  "type": "content_filter",
  "settings": {
    "patterns": [
      { "name": "us_ssn", "action": "mask" },
      { "name": "email", "action": "mask" }
    ]
  }
}
```

## Modes

Each guardrail runs in one or more of these modes, and each type runs in some of them:

| Mode | What It Checks |
| --- | --- |
| `before_request` | The request, before it reaches the model. |
| `during_request` | The request, while the model works. The response waits for the check. |
| `after_request` | The model's response, before it reaches the agent. |
| `logging_only` | The request and the response, without blocking either. |
| `before_tool_request` | An MCP tool request's arguments, before they reach the server. |
| `during_tool_request` | An MCP tool request, while the server works. |
| `after_tool_request` | An MCP tool's result, before it reaches the agent. |

## Scope

A guardrail with `always_on` runs on every request. Any other guardrail runs on the requests that name it in `guardrails`:

```json
{
  "model": "GLM-5.3-Flash",
  "messages": [{ "role": "user", "content": "My SSN is 123-45-6789. Can you update my account?" }],
  "guardrails": ["mask-pii"]
}
```

A request can add guardrails this way. It cannot turn off a guardrail that runs on every request.

## Built-In Guardrails

These types run on the instance itself, with no outside service:

| Type | What It Does |
| --- | --- |
| `content_filter` | Blocks the request or masks the match when it finds a prebuilt pattern, such as `us_ssn` or `email`, a regular expression, or a keyword. |
| `tool_permission` | Allows or denies the tools a model asks to use, by ordered rules on the tool's name, type, and arguments. |
| `model_judge` | Scores a request or a response with a model on the instance against weighted criteria, and blocks it below a threshold. |
| `custom_code` | Runs a short sandboxed function over the request or the response. |

A `custom_code` guardrail defines `apply_guardrail(inputs, request_data, input_type)`. It reads the texts in `inputs["texts"]` and returns `allow()`, `block(reason)`, or `modify(texts=...)`:

```python
def apply_guardrail(inputs, request_data, input_type):
    for text in inputs["texts"]:
        if "forbidden" in text.lower():
            return block("The word forbidden is not allowed")
    return allow()
```

## Provider Guardrails

These types send the request to an outside service, and need an account with it: `lakera` (Lakera Guard), `presidio` (Microsoft Presidio), `bedrock` (Amazon Bedrock Guardrails), and `azure_content_safety` (Azure AI Content Safety). A provider's API key and AWS keys are write-only. No response returns them, and an update sends them again with the whole `settings`.

## Blocking and Masking

How a block reaches the agent depends on the guardrail:

- A content filter or tool permission guardrail fails a model request with `400` and its reason as the error message, such as `Content blocked: us_ssn pattern detected`.
- A model judge fails it with `422` and `LLM judge rejected response: score below threshold`.
- A custom code guardrail answers the request with its reason in place of the model's response.
- A block after a stream starts closes the stream before it completes.
- A blocked tool request returns a tool result with `isError: true`.

A masking guardrail replaces each match before the request reaches the model. With the content filter, `123-45-6789` reaches the model as `[US_SSN_REDACTED]`. In a tool mode, it masks the tool's arguments before they reach the server, or the tool's result before it reaches the agent.

---

### Policies

> Source: https://developers.telnyx.com/docs/agent-gateway/authorization/policies.md

A policy is a named set of [guardrails](/docs/agent-gateway/authorization/guardrails). A policy can build on a base policy, and add guardrails to it or remove some. Attachments say where each policy applies.

[`POST /v2/agent_gateways/{id}/policies`](/api-reference/agent-gateway-policies/create-a-policy) creates one. This policy runs the guardrails of `baseline` and a custom code check, on requests for `GLM-5.3-Flash`:

```json
{
  "name": "strict",
  "base": "baseline",
  "guardrails": { "add": ["no-forbidden"] },
  "model": "GLM-5.3-Flash"
}
```

## Inheritance

A policy that builds on a base policy starts with the base's guardrails, then adds and removes its own. A `strict` policy can build on a `baseline` policy that masks personal data, and add a custom code check, so both run.

## Conditions

A policy can apply only to some models, named exactly or by a regular expression. Its guardrails then run only on requests for those models.

## Attachments

[`POST /v2/agent_gateways/{id}/policy_attachments`](/api-reference/agent-gateway-policy-attachments/attach-a-policy) applies a policy to every request, or to requests for the models it names. A model name in an attachment can use `*` as a wildcard:

```json
{
  "policy": "strict",
  "models": ["GLM-5.3*"],
  "priority": 10
}
```

An attachment with a priority applies before the others. A default attachment, with `"default": true`, applies only to the requests that no other attachment matches.

A request can also add policies by name, in `policies`:

```json
{
  "model": "GLM-5.3-Flash",
  "messages": [{ "role": "user", "content": "Summarize this support ticket." }],
  "policies": ["strict"]
}
```

Like a guardrail, a policy only adds checks. It cannot turn off a guardrail that runs on every request.

## Pipelines

A policy can run its guardrails as ordered steps instead. Each step says what happens when its guardrail passes, fails, or errors:

- `next` goes on to the next step.
- `allow` allows the request.
- `block` blocks the request.
- `respond` replaces the response with the step's `message`.

```json
{
  "name": "piped",
  "pipeline": {
    "hook": "before_request",
    "steps": [
      { "guardrail": "mask-pii", "on_pass": "next", "on_fail": "block" },
      { "guardrail": "no-forbidden", "on_fail": "respond", "message": "Not allowed." }
    ]
  }
}
```

A policy that is named by an attachment, or that another policy builds on, cannot be deleted.

---

## Traffic Control

### Budgets and Rate Limits

> Source: https://developers.telnyx.com/docs/agent-gateway/traffic/budgets-and-rate-limits.md

[Keys](/docs/agent-gateway/authentication/keys) and [teams](/docs/agent-gateway/authorization/allow-lists#teams) carry a budget and rate limits:

| Field | On | What It Limits |
| --- | --- | --- |
| `max_budget` | Keys, teams | What the key or team may spend, in USD, until the budget resets. |
| `budget_resets_every` | Keys, teams | How often spend resets, as a number and a unit (`s`, `m`, `h`, or `d`), such as `30d`. |
| `requests_per_minute` | Keys, teams | Requests per minute. |
| `tokens_per_minute` | Keys, teams | Tokens per minute. |
| `max_parallel_requests` | Keys | Requests in flight at once. |

The instance applies the stricter of a key's limit and its team's, and refuses a model request past either. A request past a budget gets `422` with the error type `budget_exceeded`. A request past a rate limit gets `429` with a `retry-after` header, in seconds. `GET {gateway_url}/v1/models` does not count toward the limits.

A request's spend and tokens count when it completes, so the request that crosses a budget completes and the next one is refused. A request whose prompt and `max_tokens` would exceed the tokens left in the minute is refused before it runs.

Budgets enforce on instances created since 2026-10-29. Instances created before that date price every request at `0`, so spend never reaches a budget and no request is refused for one (AIPLAT-1630).

## New Limits

Limits go in the body of [`POST /v2/agent_gateways/{id}/teams`](/api-reference/agent-gateway-teams/create-a-team) or [`POST /v2/agent_gateways/{id}/keys`](/api-reference/agent-gateway-keys/create-a-key):

```json
{
  "name": "support",
  "max_budget": 50,
  "budget_resets_every": "30d",
  "requests_per_minute": 120
}
```

A key's or team's `spend` and `budget_resets_at` show where it stands.

## Limit Changes

[`PATCH /v2/agent_gateways/{id}/keys/{key_id}`](/api-reference/agent-gateway-keys/update-a-key) and [`PATCH /v2/agent_gateways/{id}/teams/{team_id}`](/api-reference/agent-gateway-teams/update-a-team) change limits without reissuing anything. A field left out stays as it is, and `null` removes a limit.

```json
{
  "max_budget": 100
}
```

---

### Routing and Fallbacks

> Source: https://developers.telnyx.com/docs/agent-gateway/traffic/routing-and-fallbacks.md

**Beta.** An instance sets no routing of its own. Each request sets its own fallbacks, retries, and timeout, as on this page.

A request can retry when it fails, limit how long each attempt takes, and fall back to other models.

## Retries

An instance retries a failed request only when the request sets `num_retries`. The retries run before the request fails or falls back.

A model that keeps failing is taken out of rotation for 5 seconds, and requests for it return `429` meanwhile.

## Fallbacks

When a request fails and its retries are spent, the gateway tries the request's fallbacks in order. When every fallback fails, the response is the first model's error.

## Per-Request Settings

A request can set its own routing in the request body:

| Field | What It Does |
| --- | --- |
| `fallbacks` | The models to try, in order, if this request fails. An entry can be a model name, or an object with `model` and parameters that replace the request's own for that model. |
| `disable_fallbacks` | `true` skips the request's fallbacks. |
| `num_retries` | How many times to retry the request. |
| `timeout` | How long each attempt may take, in seconds. Without it, an attempt that is not streamed fails after 30 seconds. |
| `stream_timeout` | The same, for a streamed request. |

A fallback model must be on the key's [allow list](/docs/agent-gateway/authorization/allow-lists), or the gateway refuses the request.

## Fallback Example

This request asks `GLM-5.3-Flash` for more output tokens than it allows. Its fallback, `Qwen3.8-27B-nothink`, replaces `max_tokens` with `8`:

```bash Host
curl "$GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AGW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.3-Flash",
    "max_tokens": 100000000,
    "messages": [{ "role": "user", "content": "Say hi" }],
    "fallbacks": [{ "model": "Qwen3.8-27B-nothink", "max_tokens": 8 }]
  }'
```

`GLM-5.3-Flash` refused the request with `422`, and the fallback answered. After a fallback, `model` holds the Telnyx inference model that answered:

```json Output
{
  "id": "chatcmpl-10acb933-e5c5-42aa-aea4-82549133320a",
  "model": "Qwen/Qwen3.8-27B",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "length",
      "message": { "content": "Hi! How can I help you today", "role": "assistant", ... },
      ...
    }
  ],
  "usage": { "completion_tokens": 8, "prompt_tokens": 14, "total_tokens": 22, ... },
  ...
}
```

Without `fallbacks`, or with `"disable_fallbacks": true`, the same request returns the `422`.

---

## Audit and Observability

### Spend Logs

> Source: https://developers.telnyx.com/docs/agent-gateway/observability/spend-logs.md

[`GET /v2/agent_gateways/{id}/spend_logs`](/api-reference/agent-gateway-spend-logs/list-spend-logs) lists the requests an instance served with its [keys](/docs/agent-gateway/authentication/keys), newest first. A row appears a few seconds after its request. Rows cover model requests, MCP tool requests, and refused requests, and leave out successful `GET {gateway_url}/v1/models` requests.

## Window and Filters

| Parameter | What It Does |
| --- | --- |
| `start`, `end` | The window, as RFC 3339 timestamps with an offset. It defaults to the 24 hours before now, and spans at most 31 days. |
| `key_id` | Only the requests made with this key. |
| `team_id` | Only the requests made with this team's keys. |
| `page[number]`, `page[size]` | The page, counting from 1, and its size, 1 to 100 and 50 by default. |

```bash Host
curl -G "https://api.telnyx.com/v2/agent_gateways/32ce035d-3165-4031-b1a7-a7c0c259590a/spend_logs" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode "start=2026-10-26T00:00:00Z" \
  --data-urlencode "team_id=d7b21324-a2bf-406c-ba49-c6ec4d23d476"
```

## Rows

Each row is one request. Prompts, responses, and request metadata are not shown.

```json Output
{
  "data": [
    {
      "id": "chatcmpl-653db9ce-f80c-4497-8f33-610bcf4fde35",
      "key_id": "f739ad190d29e2a5e658c3a486111953e6c18d746fd04374962ab150aae17757",
      "team_id": "d7b21324-a2bf-406c-ba49-c6ec4d23d476",
      "model": "zai-org/GLM-5.3-Flash",
      "operation": "acompletion",
      "status": "success",
      "spend": 0,
      "prompt_tokens": 14,
      "completion_tokens": 200,
      "total_tokens": 214,
      "started_at": "2026-10-26T16:07:12.105000Z",
      "ended_at": "2026-10-26T16:07:14.042000Z",
      "duration_ms": 1937
    },
    ...
  ],
  "meta": {
    "total_results": 12,
    "page_number": 1,
    "page_size": 50,
    "total_pages": 1,
    "total_results_capped": false
  }
}
```

`model` is the Telnyx Inference model that answered. `spend` is the request's cost in USD, with its tokens at [Telnyx Inference prices](/docs/inference/models/pricing). Spend prices at list on instances created since 2026-10-29; instances created before that date record every request's spend as `0` (AIPLAT-1630), as this row does. For an MCP tool request, `model` is `MCP: ` and the tool's name. `operation` is the request type, such as `acompletion` for a chat completion or `call_mcp_tool` for a tool request. `status` is `success` or `failure`.

A window counts at most 10,000 rows. When it holds more, `total_results_capped` is `true`, and `total_results` and `total_pages` are lower bounds. Narrow the window, or page until a page comes back empty.

---

## API Reference (Agent Gateway)

### Agent Gateways

- [List Agent Gateways](https://developers.telnyx.com/api-reference/agent-gateways/list-agent-gateways.md): Lists the account's Agent Gateway instances, newest first, one page at a time.
- [Create an Agent Gateway](https://developers.telnyx.com/api-reference/agent-gateways/create-an-agent-gateway.md): Creates an Agent Gateway instance on one of the account's WireGuard Interfaces. The instance starts `pending`, moves to `provisioning`, and then to `ready` or…
- [Retrieve an Agent Gateway](https://developers.telnyx.com/api-reference/agent-gateways/retrieve-an-agent-gateway.md): Returns one of the account's Agent Gateway instances.
- [Delete an Agent Gateway](https://developers.telnyx.com/api-reference/agent-gateways/delete-an-agent-gateway.md): Deletes an Agent Gateway instance in any status. The response shows it `deleting`; repeating the request answers the same until the instance is gone, and then…
- [List an Agent Gateway's models](https://developers.telnyx.com/api-reference/agent-gateways/list-an-agent-gateways-models.md): Lists the models the instance serves. Each has the name a request uses, the Telnyx Inference model behind it, and its price per million tokens.

### Agent Gateway Keys

- [List keys](https://developers.telnyx.com/api-reference/agent-gateway-keys/list-keys.md): Lists the instance's keys, without their values. Returns the first 100. The instance must be `ready`; otherwise the request answers `409`.
- [Create a key](https://developers.telnyx.com/api-reference/agent-gateway-keys/create-a-key.md): Issues a key on the instance. The key's value is in this response only. Every field is optional; a key without `models` may use every model the instance serves…
- [Update a key](https://developers.telnyx.com/api-reference/agent-gateway-keys/update-a-key.md): Changes a key's settings without reissuing it. A field left out stays as it is, and `null` clears it. `models: []` lifts the model restriction. `expires_in` co…
- [Delete a key](https://developers.telnyx.com/api-reference/agent-gateway-keys/delete-a-key.md): Revokes a key and returns it as it was, without its value. The instance must be `ready`; otherwise the request answers `409`.

### Agent Gateway Teams

- [List teams](https://developers.telnyx.com/api-reference/agent-gateway-teams/list-teams.md): Lists the instance's teams. The instance must be `ready`; otherwise the request answers `409`.
- [Create a team](https://developers.telnyx.com/api-reference/agent-gateway-teams/create-a-team.md): Creates a team on the instance. A team is a model list, a budget, and rate limits that its keys share. Names need not be unique; the `id` identifies the team.…
- [Update a team](https://developers.telnyx.com/api-reference/agent-gateway-teams/update-a-team.md): Changes a team's settings. A field left out stays as it is, and `null` clears it. `models: []` lifts the model restriction. Setting `blocked` to `true` makes t…
- [Delete a team](https://developers.telnyx.com/api-reference/agent-gateway-teams/delete-a-team.md): Deletes a team that has no keys and returns it. A team that still has keys answers `409`; delete or move its keys first. The instance must be `ready`; otherwis…

### Agent Gateway Spend Logs

- [List spend logs](https://developers.telnyx.com/api-reference/agent-gateway-spend-logs/list-spend-logs.md): Lists the requests the instance served with its keys, newest first, one page at a time. The window defaults to the last 24 hours and spans at most 31 days. A r…

### Agent Gateway MCP Servers

- [List MCP servers](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/list-mcp-servers.md): Lists the MCP servers the instance serves at `{gateway_url}/mcp`, without their credentials. The instance must be `ready`; otherwise the request answers `409`.
- [Add an MCP server](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/add-an-mcp-server.md): Adds an MCP server. The instance serves its tools at `{gateway_url}/mcp`, each named with the server's `name` and a hyphen, to the keys granted the server and,…
- [Update an MCP server](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/update-an-mcp-server.md): Changes an MCP server's settings. A field left out stays as it is. `auth` is replaced whole, `tools: []` exposes every tool, and `static_headers: {}` clears th…
- [Delete an MCP server](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/delete-an-mcp-server.md): Removes an MCP server and returns it as it was. Its `id` stays in the tool permissions that name it until they are next set. The instance must be `ready`; othe…

### Agent Gateway APIs

- [List APIs](https://developers.telnyx.com/api-reference/agent-gateway-apis/list-apis.md): Lists the REST APIs the instance serves as tools, without their credentials. The instance must be `ready`; otherwise the request answers `409`.
- [Add an API](https://developers.telnyx.com/api-reference/agent-gateway-apis/add-an-api.md): Adds a REST API by its OpenAPI description. Each operation becomes a tool at `{gateway_url}/mcp`, named with the API's `name`, a hyphen, and the lowercased `op…
- [Update an API](https://developers.telnyx.com/api-reference/agent-gateway-apis/update-an-api.md): Changes an API's settings. A field left out stays as it is, `"base_url": null` clears the base URL, and `auth` is replaced whole. The instance must be `ready`;…
- [Delete an API](https://developers.telnyx.com/api-reference/agent-gateway-apis/delete-an-api.md): Removes an API and returns it as it was. An MCP server's `id` answers `404`. The instance must be `ready`; otherwise the request answers `409`.

### Agent Gateway Tool Permissions

- [Retrieve a key's tool permissions](https://developers.telnyx.com/api-reference/agent-gateway-tool-permissions/retrieve-a-keys-tool-permissions.md): Returns the MCP servers and APIs the key may use, and the tools within each. `servers: []` means none. The instance must be `ready`; otherwise the request answ…
- [Set a key's tool permissions](https://developers.telnyx.com/api-reference/agent-gateway-tool-permissions/set-a-keys-tool-permissions.md): Replaces the grant whole and returns it. Every server must be one of the instance's MCP servers or APIs, named once. A key reaches the servers granted to it or…
- [Retrieve a team's tool permissions](https://developers.telnyx.com/api-reference/agent-gateway-tool-permissions/retrieve-a-teams-tool-permissions.md): Returns the MCP servers and APIs the team's keys may use, and the tools within each. `servers: []` means none. The instance must be `ready`; otherwise the requ…
- [Set a team's tool permissions](https://developers.telnyx.com/api-reference/agent-gateway-tool-permissions/set-a-teams-tool-permissions.md): Replaces the grant whole and returns it. Every server must be one of the instance's MCP servers or APIs, named once. A key reaches the servers granted to it or…

### Agent Gateway Guardrails

- [List guardrails](https://developers.telnyx.com/api-reference/agent-gateway-guardrails/list-guardrails.md): Lists the instance's guardrails, without their secrets. The instance must be `ready`; otherwise the request answers `409`.
- [Add a guardrail](https://developers.telnyx.com/api-reference/agent-gateway-guardrails/add-a-guardrail.md): Adds a check the instance runs on model and tool requests. It runs on every request when `always_on`, and otherwise on the requests that name it in `guardrails…
- [Update a guardrail](https://developers.telnyx.com/api-reference/agent-gateway-guardrails/update-a-guardrail.md): Changes a guardrail's `name`, `modes`, `always_on`, or `settings`. `settings` is replaced whole, secrets included. The `type` cannot change. The instance must…
- [Delete a guardrail](https://developers.telnyx.com/api-reference/agent-gateway-guardrails/delete-a-guardrail.md): Removes a guardrail and returns it as it was. The instance must be `ready`; otherwise the request answers `409`.

### Agent Gateway Policies

- [List policies](https://developers.telnyx.com/api-reference/agent-gateway-policies/list-policies.md): Lists the instance's policies, each in its current version.
- [Create a policy](https://developers.telnyx.com/api-reference/agent-gateway-policies/create-a-policy.md): Creates a named set of guardrails. It applies from the next request on, to the requests that name it in `policies` and to those its attachments match.
- [Retrieve a policy](https://developers.telnyx.com/api-reference/agent-gateway-policies/retrieve-a-policy.md): Returns one policy, in its current version.
- [Update a policy](https://developers.telnyx.com/api-reference/agent-gateway-policies/update-a-policy.md): Changes a policy, which publishes a new version of it. A field left out stays as it is; `guardrails` and `pipeline` are replaced whole, and `model: null` remov…
- [Delete a policy](https://developers.telnyx.com/api-reference/agent-gateway-policies/delete-a-policy.md): Deletes a policy and every version of it, and returns it as it was. A policy that an attachment names, or that another policy builds on, cannot be deleted.

### Agent Gateway Policy Attachments

- [List policy attachments](https://developers.telnyx.com/api-reference/agent-gateway-policy-attachments/list-policy-attachments.md): Lists where the instance applies each policy.
- [Attach a policy](https://developers.telnyx.com/api-reference/agent-gateway-policy-attachments/attach-a-policy.md): Applies a policy to every request, or to the requests for the models named. It applies from the next request on.
- [Detach a policy](https://developers.telnyx.com/api-reference/agent-gateway-policy-attachments/detach-a-policy.md): Removes an attachment and returns it as it was. The policy stays.