API Registry

The API Registry is where you bring your existing REST APIs under governance so agents can call them safely. You register an API from its OpenAPI (Swagger) spec, pick exactly which endpoints to expose, and the AI Gateway proxies every call — applying the same authentication, data protection, rate limiting, and audit it applies to MCP tools. You then grant a registered API (or a subset of its endpoints) to an Agent Persona, and the agents connecting to that persona can call those endpoints through the gateway.

In short: MCP servers give agents tools; the API Registry gives agents governed REST endpoints — without you having to build or host an MCP server for the API.

Quick Start: What do you want to do?

I want to...	Jump to
Understand what the API Registry is and when to use it	What is the API Registry?
Register my first API	Registering an API
Choose which endpoints to expose	Selecting endpoints
Let the gateway authenticate to the real API	Connecting to the upstream API
Give an agent access to an API	Granting an API to a persona
Understand how agents call the API	How agents call registered APIs
Decide between an API Registry entry and an MCP server	API Registry vs. MCP server

What Is the API Registry?

Most organizations already have REST APIs — internal services, partner APIs, SaaS products with an OpenAPI spec. The API Registry lets you expose those APIs to agents without writing any glue code:

Register from a spec. Upload an OpenAPI/Swagger file (or pick one from the App Catalog) and the gateway learns every endpoint.
Expose only what you choose. Select a subset of endpoints so agents can't reach operations you didn't intend.
Governed like everything else. Every call flows through the gateway, which handles upstream authentication, redaction and data-loss prevention (DLP), rate limits, and full audit logging.
Grant per persona. Attach an API — or just specific endpoints of it — to the agent personas that need it.

What it does for you:

No servers to build. Point the gateway at an OpenAPI spec and you're done — there's nothing to host.
Least privilege. You control which endpoints exist in the registry, and each persona can be granted an even narrower subset.
Credentials stay with the gateway. Agents never see your API keys or tokens. The gateway injects them on the way out.

Use Cases

Bring an internal API to your agents

Register your company's internal "Orders" or "Inventory" API and expose just the read endpoints, so a support agent can look up order status without touching write operations.

Give an agent a partner or SaaS API

Register a third-party API (for example a payments or shipping provider) and let the gateway hold the API key. Agents call the endpoints; the credential never leaves the gateway.

Combine APIs and tools in one persona

Grant an agent persona a mix of MCP tools (from your connected apps) and REST endpoints (from the API Registry). The agent works across both from a single connection.

Registering an API

Select API Registry in the sidebar.
Select Add API. Choose how to provide the spec:

Option	Use when
Upload OpenAPI spec	You have an OpenAPI/Swagger file to import (YAML, YML, JSON, WSDL, or XML).
From app catalog	The spec is already available in your catalog or the prebuilt third-party catalog.

The Create API wizard opens.

Step 1: Provide the API spec

Upload path — Drag and drop your OpenAPI/Swagger file (or Browse Files), then select Upload & Continue. The maximum file size is 25 MB.
Catalog path — Search for and select an existing spec under Your specs or the Third-party catalog.

Step 2: Select the base URL and endpoints

Confirm the Base URL — the address the gateway will call. It's pre-filled from the spec's servers; you can pick another or type your own.
Choose the endpoints to expose. This is your first least-privilege control:
- Search and filter by HTTP method (GET, POST, etc.).
- Group by methods or by tags.
- Check individual endpoints, or use Select All to include the whole filtered set.

Expose only what agents need

Only select the endpoints your agents will actually use. You can always register more later, and each persona can be granted an even narrower subset.

Step 3: Name and finalize

Give the API a Name (for example, "Orders API") and an optional Description. Set deployment options (cloud or a private pool) as needed.

Step 4: Inbound authentication

Choose how callers authenticate to the gateway for this API. Options include:

Option	Best for
Interactive Login (OAuth)	People using AI clients — they sign in and act as themselves
Passthrough	Callers that manage their own tokens (optionally validate incoming JWTs)
API Key / Bearer Token / Basic / JWT Bearer	Programmatic callers using a static credential
OAuth 2.1 (Authorization or Client Credentials)	Standards-based delegated or service-to-service access

Step 5: Review and deploy

Review the summary — API name, base URL, selected endpoints, and authentication — then select Create & Deploy. The API appears in the registry and is ready to grant to personas.

Upstream authentication comes next

The wizard configures how callers reach the gateway. How the gateway authenticates to the real API is configured on the API's detail page after you create it — see Connecting to the upstream API.

Connecting to the Upstream API

For the gateway to call the real API on an agent's behalf, it usually needs a credential. Configure this on the API's detail page:

Open the API from the API Registry.
Go to the Authentication tab. You'll see two cards:
- Agent Authentication — how callers authenticate to the gateway (set during the wizard).
- App Authentication — how the gateway authenticates to the upstream API.
On App Authentication, select Edit and choose the upstream auth type:

Type	How it works
Passthrough	Forward the caller's own token to the upstream API
API Key	Inject a stored key into a header or query parameter
Bearer Token	Add a stored token as `Authorization: Bearer …`
Basic Authentication	Send a stored username and password
OAuth 2.1 Client Credentials	The gateway fetches a service token automatically
OAuth 2.1 Authorization	The gateway exchanges the signed-in user's identity for an upstream token (the user connects once)

You can also use Upstream Authentication & Headers for ready-made recipes — for example forward the caller's token, use an OAuth2 service token, act on behalf of the caller, or add custom headers.

Credentials stay in the gateway

You reference a stored credential — the gateway injects the actual secret at call time. Agents never see your keys or tokens.

Managing a Registered API

Selecting an API opens its detail page, which reuses the same layout as MCP servers, with these tabs:

Tab	What it shows
Overview	API details, deployment, and an Available Endpoints card showing which endpoints are exposed
Endpoints	A read-only, Swagger-style browser of the exposed endpoints — search, filter by method, and expand to see parameters and responses. The badge shows how many endpoints are enabled.
Authentication	Agent (inbound) and App (outbound) authentication
Risk-based Throttling	Rate limits (admin)
Network Policy	Egress/network controls (admin)

To change the API's name, description, or endpoints, select Edit to reopen the wizard. To remove it, select Delete.

Granting an API to an Agent Persona

A registered API only becomes usable once you grant it to a persona. Only endpoints you grant can be called — this is the per-persona least-privilege control.

In the Create Agent Persona (or Edit) wizard, on the Capabilities step:

Expand the API Endpoints section (it sits alongside Tool Selection and Skills).
For each registered API you want to grant:
- Check the whole API to grant all endpoints, or
- Expand the API and check specific endpoints (use Select all / Clear all to move quickly).
Finish the wizard. The persona now shows a Tools & Endpoints tab summarizing everything the agent can use.

tip

If an API isn't in the list, register it in the API Registry first. The persona builder can only grant APIs that already exist in the registry.

How Agents Call Registered APIs

Agents don't get a separate tool for every endpoint (which would overwhelm them on large APIs). Instead, the gateway uses a simple discover → look up → invoke pattern:

Discover. The agent lists the endpoints it's been granted (name, method, and a short summary).
Look up. The agent retrieves the details for the specific endpoint it wants — the parameters and expected inputs.
Invoke. The agent calls the endpoint. The gateway then:
- Confirms the endpoint is actually granted to this persona (ungranted endpoints are refused).
- Injects the upstream credential you configured.
- Applies data protection (redaction/DLP), rate limits, and network policy.
- Proxies the call to the real API and returns the response.
- Records the call in the audit log.

Because everything runs through the gateway, agents never see upstream URLs or credentials, and they can only reach the endpoints the persona was granted.

API Registry vs. MCP Server

The same OpenAPI spec can be exposed two ways. Both are governed identically; the difference is how the agent interacts with it.

	API Registry	MCP server (from an API spec)
What the agent sees	REST endpoints it discovers and invokes	Individual MCP tools, one per operation
Best when	The API has many endpoints, or you want direct REST semantics	You want each operation to appear as a distinct, named tool
Granted to a persona via	API Endpoints (whole API or a subset)	Tool Selection (individual tools)
Scales to large APIs	Yes — the agent browses endpoints on demand	Better for a focused set of operations

You can register the same underlying API both ways if different personas need different experiences. In the App Catalog, an app's detail view offers both Add to API Registry ("directly expose API endpoints to the agent") and Add to MCP Registry ("expose as MCP tools").

Real-World Example

"I want my support agent to look up orders, but never modify them."

In the API Registry, select Add API → Upload OpenAPI spec and upload your Orders API spec.
In API Configuration, filter to GET endpoints and select only GET /orders/{id} and GET /orders. Select Next.
Name it "Orders API (read-only)" and finish the wizard, choosing Interactive Login for inbound auth.
On the API's Authentication tab, set App Authentication to your stored Orders API key.
Open your Support Triage persona → Capabilities → API Endpoints, expand Orders API (read-only), and grant the two GET endpoints.

Now the support agent can answer "What's the status of order 12345?" — and it physically cannot place or cancel an order, because those endpoints were never exposed.

Tips

Start read-only. Expose GET endpoints first; add write operations only when you have a clear, governed use for them.
Register narrow, grant narrower. Keep the registry entry limited to relevant endpoints, then grant each persona the smallest subset it needs.
Let the gateway hold credentials. Configure upstream authentication once on the API, so no agent or client ever handles the secret.
Name endpoints' purpose in the description. A clear API name and description help both your team and the agent understand what it's for.
Choose the right shape. Use the API Registry for large or REST-native APIs; expose an MCP server when you want a small, named set of tools.

Quick Start: What do you want to do?​

What Is the API Registry?​

Use Cases​

Bring an internal API to your agents​

Give an agent a partner or SaaS API​

Combine APIs and tools in one persona​

Registering an API​

Step 1: Provide the API spec​

Step 2: Select the base URL and endpoints​

Step 3: Name and finalize​

Step 4: Inbound authentication​

Step 5: Review and deploy​

Connecting to the Upstream API​

Managing a Registered API​

Granting an API to an Agent Persona​

How Agents Call Registered APIs​

API Registry vs. MCP Server​

Real-World Example​

Tips​