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

# Connect your API

> Connect your own HTTP API from its OpenAPI document so an endpoint can search it

Connect your own REST API as a Source. Raily reads the API's OpenAPI document, lists its operations, and sets up each one you pick so an endpoint can search it. Nothing is copied or indexed: every search calls your API live.

> [!NOTE]
>
> The API source is available on request. [Contact us](https://www.raily.ai/contact) to turn it on for your Account.

## Before you start

* **An OpenAPI document for the API.** OpenAPI 3.x or Swagger 2.0, in JSON or YAML. Raily fetches it over the web, so it needs a public address.
* **The API's credentials**, if it needs any: an API key or a bearer token.
* **A public HTTPS address.** Raily calls the API from the internet, so the host must resolve to a public address.

## Connect the API

**1. Open the API connector**

In the Rail, click **Connect source**, then choose the **API** card.

**2. Name the Source**

Enter a **Name**. This is how the Source appears in your workspace.

**3. Enter the Base URL**

Type the API's host in **Base URL**, for example `api.example.com`. Raily assumes `https://` and each operation adds its own path.

You can also paste a link to the API's docs page (a Swagger UI page, for example). Raily finds the document behind it and replaces the field with the address the API answers on.

**4. Set authentication**

Choose an **Authentication** option:

* **None**
* **API key header**: enter the **Header name** (for example `x-api-key`) and the **Secret value**.
* **Bearer token**: enter the **Token**.
* **Query parameter**: enter the **Query parameter name** and the **Secret value**.

If the OpenAPI document declares how the API signs in, Raily selects that option and fills in the name for you. You still enter the secret yourself. The secret is sent with every call this Source makes. Your agents and their users never see it.

Optionally change **Default method** (GET or POST) and **Timeout (seconds)**, which accepts 1 to 120 and starts at 30.

**5. Find the operations**

Click **Find operations**. Raily looks for the OpenAPI document at the usual paths on your host.

If it can't find one, an **OpenAPI document URL** field appears. Enter the document's full URL, then click **Find operations** again.

**6. Pick what to search**

Raily sorts the operations by what they do, not by their names:

* **Search**: takes a question or filter and answers with a list of records. This is what an endpoint searches. These are selected for you.
* **Lists**: returns a list but takes no query.
* **Look up one record**: needs a value in the path, such as an id or a name.
* **Other**: writes data, runs an action, or answers with a file. Operations that write data are shown but can't be selected.

For a **Look up one record** operation you select, an **example** box appears next to each path value (for example **example id**). Enter a real value. Raily uses it once, to learn what the operation answers.

**7. Create the Source**

Click **Create Integration**. Raily saves the connection and starts setting up every selected operation right away. You land on the Source page.

## What happens after you create it

While setup runs, each operation row reads **configuring…** and a note at the top counts how many are left. Raily calls each operation once to learn what a record looks like, then writes its search setup from the OpenAPI document: how to read a question, which parameters to fill, and a few suggested prompts. Expect about a minute per operation, three at a time. You can leave the page; setup keeps going.

When an operation is done, its row shows one of these:

| Row label | What it means |
| - | - |
| **ready · no endpoint** | Set up and ready to search. No endpoint uses it yet. |
| **live** | At least one endpoint searches it. |
| **from the contract** | The sample call didn't return a record, so Raily set it up from the document alone. The row says why. Run it under **Test** to check the answer. |
| **couldn't configure** | Setup failed. The row says why and what to do next. |
| **config behind the API** | The API's document changed since this operation was set up. |

The header shows the Source as **Ready** until an endpoint uses one of its operations, then **Serving 1 endpoint** (or more).

## Search the API from an endpoint

Under **Searched by** on an operation row, click **create endpoint** (or **add endpoint** if your Account already has endpoints). Pick an existing endpoint or **Create a new endpoint for** the operation, then click **Create endpoint**. Raily wires the operation and runs a live test, which can take up to a minute. A new endpoint opens in the chat so you can try it right away.

### How a question becomes an API call

When someone asks the endpoint a question, Raily reads it and fills in the operation's parameters: the search text goes into the operation's own search parameter, and dates, categories or other values the question names go into the parameters the document describes. Raily then calls your API with the Source's credentials and shows each record as a result with its title, text, and author where the API provides them.

Raily only fills parameters the document describes, so a clear description on each parameter in your OpenAPI document leads to better calls.

## Test an operation

Open an operation from its row menu (**Open operation**). Under **Test this operation**, fill in sample arguments and click **Run test**. Raily calls your API directly and shows:

* **Request built**: the request it sent, with secrets hidden.
* **Response**: what the API returned.

A test that returns data saves those arguments as the operation's sample. To have Raily set the operation up again from that answer, go back to the Source page and choose **Regenerate config** from the row menu.

On the same page you can change the **Display name** and set a **Response pick (optional dotted path)**, such as `data.results`, to return only part of the JSON body. Click **Save operation** to keep your changes.

## Keep operations in sync

If the API changes, open the Source menu and choose **Refresh from API**. Raily re-reads the document and updates your operations. To add operations you didn't pick the first time, click **Edit connection** (the pencil icon) and use **Find operations** again.

## Next steps

> [card] [Create an AI endpoint](https://docs.raily.ai/concepts/ai-endpoints.md)
>
> Let agents search this source

> [card] [Agentic Layer](https://docs.raily.ai/concepts/agentic-layer.md)
>
> See how Raily reads and answers a request


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