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.
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.
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.
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