Skip to main content
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.
The API source is available on request. Contact us 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: 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

Create an AI endpoint

Let agents search this source

Agentic Layer

See how Raily reads and answers a request