> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Connect a REST API

> Connect a REST API as a connection, either manually or by importing an OpenAPI spec that generates its routes.

**Services** connects plain HTTP APIs the same way you connect LLM providers and MCP servers. You can add a connection yourself, or import an OpenAPI spec to generate the connection and its routes automatically. This topic shows you how to add a connection, import a spec, review the plan, create the connection, and update the routes later.

## Prerequisites

Before you begin, make sure you have the following:

* Access to a Fabric AI Gateway organization, with permission to create connections.
* An OpenAPI document for the API, in JSON or YAML.

## Add a connection

To add a REST API connection yourself, do the following:

1. In the sidebar, select **Services**.
2. Select **Create connection**. The **Create HTTP connection** page opens.
3. For **Source**, keep **Manual**. To generate the connection and its routes from an OpenAPI document instead, select **Import OpenAPI spec**, and then follow [Import an OpenAPI spec](#import-an-openapi-spec).
4. In **Connection**, enter a **Connection name** and the **Target URL** of your API, and choose the **Access** mode.
5. In **Upstream auth**, keep **Auth type** set to **None**, or select **API key**, **Bearer token**, or **Basic auth** and enter the credential. **Basic auth** appears only if your organization runs its own data plane.
6. In **Gateway route**, keep **Create gateway route** selected, enter a **Route name**, and set the path that clients call. Select **Add path** to add more paths.
7. Keep **Gateway auth** set to **Gateway key**, so callers must send a gateway key in the `fg-api-key` header.
8. Select **Create connection**.

## Import an OpenAPI spec

To import a spec, select **Import OpenAPI spec** as the **Source** on the **Create HTTP connection** page.

### Step 1: Provide the spec

In **OpenAPI spec**, paste a JSON or YAML OpenAPI document, or select **Choose file** to upload one. The spec can be up to 6 MB. Under **Import mode**, select one of the following:

| Import mode   | Behavior                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------- |
| **Merge**     | Adds and updates routes from the spec, and leaves routes that aren't in the spec untouched. |
| **Overwrite** | Matches the spec exactly, and removes any routes that aren't in it.                         |

Optionally, select **Add route prefix, import ID, upstream URL override, and variables** to set the following:

* **Route prefix** — Mounts every route from the spec under a path prefix. Fabric strips the prefix before it forwards the request upstream, so multiple imported APIs don't collide.
* **Import ID** — A stable identifier, so re-imports keep updating the same API instead of creating a new one.
* **Upstream URL override** — Overrides the base URL for the upstream service.
* **Variables** — Values for the `{…}` placeholders in your spec's server URL, if it has any.

### Step 2: Review the plan

Select **Preview**. Fabric checks the spec without changing anything, and shows an **Import summary**: the **Connection name**, **Target URL**, and **Upstream auth**, followed by how many routes are new, changed, or unchanged, and the exact route paths and methods.

**Upstream auth** shows the auth scheme that the spec declares. Imported connections pass each caller's own credentials through to the upstream. To have the gateway authenticate to the upstream instead, add an upstream credential on the **Credentials** page after you create the connection. For the steps, see [Manage credentials and vaults](/configure/credentials).

An import doesn't add gateway auth to the routes it creates. To require a gateway key on them, add a Key Auth plugin instance. For more information, see [Authenticate requests with Key Auth](/configure/authentication/key-auth).

### Step 3: Create the connection

Select **Create connection** to apply the plan. If the import updates a connection that you imported before, the button is **Update connection**.

## Re-import to update routes

Re-importing an updated spec in **Merge** mode applies incremental updates. For example, adding a `PUT` operation to an existing path and adding a new path produces a plan that shows 1 new, 1 changed, and 3 unchanged routes, with an option to expand and view the unchanged ones.

Routes from multiple imports appear together under **Services** > **Routes**. For example, two connections imported from the same spec at different times can contribute a combined 10 routes across `albums`, `comments`, `posts` (with both `GET` and `PUT`), `todos`, and `users`.

## Next steps

* To add authentication, rate limiting, or transforms to the imported routes, see [Control traffic with plugins](/configure/plugins).
* To monitor traffic on the imported routes, see [Monitor gateway traffic](/use/monitor).