Call API

This tutorial walks you through registering an external API so your agent can call it automatically during conversations. By the end, you will have a working API action, know how to test it without leaving qlar, and understand which advanced options are available when you need them.

How qlar Calls Your API

qlar does not require you to write any code to connect an API. Instead, you describe the API in plain language and qlar passes that description to the AI model as a function tool. Here is what happens on every conversation turn:

1. The AI reads the user's message and decides — based on your description — whether it needs to call the API to give an accurate answer.
2. qlar makes the HTTP request to your endpoint, automatically extracting the required parameters from the conversation.
3. Your server responds with data in any format (JSON, plain text, etc.).
4. The AI reads the response and incorporates it into a natural-language reply.

The detection → API call → response cycle happens automatically. You register the API once; the AI decides when and how to use it.

Scenario Used in This Tutorial

To keep things concrete, this tutorial uses REST Countries — a free, public API that returns information about countries (capital, currency, population, and more). No registration or API key is required, so you can follow along and test the result immediately.

Once you are comfortable with the steps, swap in your own endpoint.

Step 1 — Open Custom API

Click the hamburger menu (☰) in the top-left corner to open the sidebar. Expand Actions, then click Custom API.

The Custom API page loads. It shows all API actions already registered for this agent.

Step 2 — Add a New API

Click the Add New API button in the top section of the page. A sliding panel opens on the right side of the screen with a blank configuration form.

Step 3 — Fill in the Action Name and Description

The Basic Information section is the most important part. The AI uses the name and description to decide when to call this API, so clarity here directly affects how well the integration works.

Action Name

Type get_country_info in the Action Name field.

Tip: Use snake_case and keep names short but specific. The AI model reads this name, so get_country_info is clearer than countries or lookupCountry.

Description

In the Description field, explain what the API returns and when it should be called. Write this as if you are briefing the AI:

Retrieves general information about a country by name, including its capital city, official currency, population, and region. Call this API when the user asks about a specific country — for example "Tell me about Japan" or "What is the capital of Brazil?".

Step 4 — Set the HTTP Method and Endpoint

Scroll down to the HTTP Method and Target URI fields.

1. Set HTTP Method to GET.
2. In Target URI, enter the full URL of your endpoint: https://restcountries.com/v3.1/name/{country}

Note: {country} is a path parameter — it will be replaced by the value the AI extracts from the conversation. You will define it as a property in Step 7.

Step 5 — Configure a Loading Text

While qlar waits for your API to respond, it can show a brief message to the user.

1. Set Loading Text Type to Fixed.
2. In the Loading Text field that appears, enter: Looking up country information, one moment...

Tip: Keep loading text short and action-oriented. It disappears as soon as the API responds. See Loading Text Types for the dynamic option, which generates a context-aware message automatically.

Step 6 — Skip Authentication (Public Endpoint)

For this scenario the endpoint is public. Leave Auth Type set to none and move on.

If your API requires credentials, see Authentication Options at the bottom of this page.

Step 7 — Add a Parameter

Parameters tell the AI what values to extract from the conversation and pass to your API. Even when a parameter is optional on the API side, declaring it here lets the AI pass user-provided context more accurately.

Click Add New Property at the bottom of the Properties section. A new property row appears.

Fill in the fields:

Tip: The Property Description is read by the AI. A precise description — including valid value examples — reduces the chance of the AI sending an unexpected value (e.g., a country code instead of a full name).

About Location: path means the value is injected directly into the URL in place of {country}. Use query for parameters appended as ?key=value, and body for POST request payloads.

Step 8 — Add Rules (Optional)

The Rules field gives the AI instructions on how to handle the API response: what to do when data is missing, how to structure the output, or what constraints to apply.

Example rules for this API:

From the API response, extract and present the following fields only: common name, capital city, official currency name and symbol, population (formatted with thousands separators), and region. If the country is not found, let the user know politely and ask them to check the spelling.

Leave this field blank for now if you want to keep things simple and add rules later.

Step 9 — Save the API to the Form

Click the Add New API button at the bottom of the sliding panel. The API is added to the list on the main page and the panel closes.

Note: The API is saved to the local form only. It is not yet live on your agent.

Step 10 — Publish All Changes

Click Save all changes at the bottom of the Custom API page. A confirmation dialog appears — click Confirm to publish.

Your agent now has access to get_country_info in all new conversations.

Step 11 — Test the API

Before going live, verify that qlar can reach your endpoint and that the response looks correct.

1. In the API list, find get_country_info and click the edit (pencil) icon to reopen its configuration panel.
2. At the bottom-left of the panel, click Test API. The panel switches to Test Mode.
3. In the country parameter field, type indonesia.
4. Click Send Request.
5. The panel shows the HTTP response — status code and body.

A successful response looks like this (abbreviated):

[
  {
    "name": { "common": "Indonesia", "official": "Republic of Indonesia" },
    "capital": ["Jakarta"],
    "currencies": { "IDR": { "name": "Indonesian rupiah", "symbol": "Rp" } },
    "population": 273523615,
    "region": "Asia"
  }
]

If the response shows the correct data, the API is ready to use. Click Back to Configuration to return to the form.

Tip: Try a few different countries (e.g., japan, brazil, nonexistentcountry) to confirm your Rules field handles both valid and not-found responses correctly.

Verifying in a Conversation

Open the live preview panel on the right side of any config page and send a message that should trigger the API:

"Tell me about Indonesia."

or

"What is the capital of Japan?"

The loading text (Looking up country information, one moment...) should appear briefly, followed by a response that incorporates the country data.

Advanced Features

The steps above cover the most common setup. The sections below explain features you may need as your integration grows.

Authentication Options

qlar supports five authentication methods. Select the Auth Type in the Authentication section and the required fields will appear.

For bearer, enter the token in the Key field. For basic, enter a Username and Password. For custom, enter the Header Name (e.g., X-API-Key) and the Key value. For oauth, select the provider type, enter the Token URL, and supply the credentials for your grant type.

Response Prompt

The Response Prompt field describes exactly how the AI should present the API result to the user — tone, format, and level of detail. This is separate from Rules, which governs how the AI interprets the raw data.

Example for Brew:

Present the specials in a friendly, conversational tone. Format each item as a bullet point with the name and price. End with an invitation to ask for more details about any item.

Send Metadata

When Send Metadata is enabled, qlar appends conversation context to every request. Use this when your API needs to personalise the response based on the user's identity or channel.

Additional Properties

By default, the AI is restricted to the parameters you define in the Properties section. Enabling Additional Properties allows the AI to pass extra key-value pairs beyond what is explicitly listed — useful for flexible or dynamic API contracts.

Loading Text Types

dynamic is useful when one API action is used in different contexts and a generic fixed text would feel out of place.

Related Pages

• Automate with Custom API — chain multiple API calls and build automated workflows
• Automate with Plugins — use pre-built plugin integrations instead of configuring raw APIs
• Observe Feedback and Logs — monitor API calls and debug responses in production