Custom REST API

An API Integration connects any REST API to Harmona: your own backend, an internal service or a third-party API that is not in the catalog. You describe the endpoints once, and agents call them when a question needs them.

Create the integration

1. 1Go to Studio → Integrations, click Add Integration and choose API Integration under Custom APIs.
2. 2Enter an Integration Name and a Description of what the API is for.
3. 3Enter the Base URL, for example `https://api.example.com`.
4. 4Choose the Authentication Type: Bearer Token, API Key (with the Header Name), Basic Auth or No Authentication, and fill in the credentials.
5. 5Optionally add API Documentation in Markdown: rules, ID formats, examples. Agents read it before they call the API.
6. 6Click Create Integration. Then open the integration from the list to add its endpoints.

Add endpoints

Click Add Endpoint. There are two ways to describe it.

• Import from cURL: give the endpoint a Name and Description, then paste a working cURL command. Harmona reads the method, path, query parameters and body from the command and writes a description for each parameter. It doesn't call the endpoint.
• Structured Entry: set the HTTP Method and Path Template, for example `/customers/{customer_id}/orders`. Then list the Path Parameters, Query Parameters, Request Headers and Request Body Properties, each with a description and whether it is Required.

Endpoints you add by hand are not analyzed automatically. After saving, click Re-analyze so Harmona writes the parameter descriptions. You cannot edit an endpoint while its analysis is running.

Write good descriptions

Agents choose endpoints and fill parameters from your descriptions. Say what each endpoint returns and when to use it, and describe each parameter's format, for example "10-digit order number". Add only the endpoints you want agents to call.

Use it

Attach the integration to an agent or a Worker like any other integration, or call its endpoints from workflow steps. Share it from the Integrations page to let others use it. See How integrations work.