Import an OpenAPI Schema
Open in CMSInstead of adding API actions one by one, you can import several at once from an existing OpenAPI (Swagger) definition. In this tutorial you import Kirana's sample Projects API schema into Atlas, Kirana Group's operations assistant. The schema has two operations: get_project_status, which Atlas already has from Connect Your API, and list_projects, which is new. You see how the import wizard adds new APIs and replaces existing ones with the same name.
Before you start
- You have registered at least one API by hand in Connect Your API, so you know what each field means. This tutorial assumes
get_project_statusfrom that page is already on the Custom API page. - You have an OpenAPI 3.x spec for your backend, as a JSON or YAML file or as text you can paste. To follow along, download the sample schema kirana-projects-openapi.json.
- You know how to test and publish changes. See Preview and Publish Changes.
When to Use This Feature
Use Import OpenAPI schema when you already have an OpenAPI spec for your backend. Rather than filling in the name, HTTP method, endpoint, and parameters for each operation by hand, qlar reads the spec and creates all the API actions in one go.
Common scenarios:
- You exported a spec from Postman, Swagger UI, or your API gateway
- Your backend team maintains an OpenAPI file as part of their development workflow
- You are migrating a large set of endpoints from another tool
The Sample Schema
kirana-projects-openapi.json describes the same public, read-only sample API used in Connect Your API. Its server URL is https://stpusakaappassetprod.blob.core.windows.net/docs-media/samples/kirana-api, and it has two operations:
operationId | Request | What it returns |
|---|---|---|
get_project_status | GET /projects/{projectCode}.json | Status, progress, budget and current approval stage of one project |
list_projects | GET /projects/index.json | Codes, names and statuses of all active Kirana projects |
Step 1: Open the Import Wizard
On the Custom API page, open More actions and click Import OpenAPI schema. The Import OpenAPI schema side panel opens. A stepper at the top shows the four steps of the wizard: Upload, Edit, Review and Done. The panel opens on Upload.
Step 2: Upload the Schema
The Upload step has two groups, Schema and Authentication.
-
Schema format: choose JSON or YAML. For the sample, choose JSON. You must choose a format before you can go on: the editor stays disabled until you do.
-
Optional file upload: the drop area reads Drop a JSON or YAML file here and has a Choose file button. Drag
kirana-projects-openapi.jsononto the drop area, or click Choose file and select the file. After the upload, the file name and size show with Replace and Remove. Remove also clears the schema text. When you upload a file, qlar sets Schema format from its extension (.json,.yamlor.yml). Uploading is optional: you can also paste the schema in the next step. -
Authentication: a group with one choice, Authentication for the imported APIs:
- Keep what each API has now, or none for a new API (the default): new APIs are imported without authentication, and APIs that already exist keep the authentication they have.
- Use the same authentication for every imported API: authentication fields appear, and every imported API gets the authentication you enter here.
The sample API is public, so leave the first option selected.

Click Next. If you have not chosen a schema format, Next shows the error "Schema Format is required".
Step 3: Edit the Schema
The Edit step shows the schema in the OpenAPI schema editor. If you uploaded a file, its content is already there. Otherwise, paste your spec into the editor now. You can still make changes here before the import, for example to fix a description. The editor stays empty until you upload a file or paste a schema, and Next shows "API Schema is required" until it has content.

Click Next. qlar converts the schema. If the schema cannot be read, a dialog reports "Couldn't convert the schema" with the reason, and you stay on this step. To change the file or the format, click Back.
Step 4: Review What Will Change
The Review step shows What the import changes. The line under the title counts the APIs, for example "1 new, 1 replaced", and says that nothing is saved until you save the page. Below it, the table APIs in the schema lists every API with these columns:
- Change: New when no API on this agent has that name yet, or Replaced when one already does. Names match even when capital letters or spaces at the start or end differ.
- Name, Method and Endpoint.
For the sample, list_projects is New and get_project_status is Replaced.

Replaced APIs take the schema's fields: a replaced API gets the description, method, endpoint and parameters from the schema. Its rules, response prompt and loading text stay. Its authentication stays too, unless you chose Use the same authentication for every imported API. In the sample,
get_project_statusgets the schema's slightly shorter description. If you prefer your own wording, edit it after the import.
If the schema has no APIs, the table is replaced by "The schema has no APIs to import." and the import button stays disabled.
Click Import 2 APIs. The button shows how many APIs the import adds or replaces. To change anything first, click Back.
Step 5: Finish the Import
The Done step shows Import complete and the message "Imported 2 APIs (1 new, 1 replaced). Check their authentication, then save the page to keep them." Only Close is left to click.

Click Close. The Custom API list now shows both get_project_status and list_projects.
Step 6: Review the Imported APIs
Click each imported API to open its drawer and check the name, description, HTTP method, endpoint, and properties. Imported APIs start with an empty Rules and Response Prompt, so add them where they help. For list_projects, for example:
- Rules:
List only projects that appear in the response. Do not add projects from memory. - Response Prompt:
Show one line per project: code, name and status.
Click Apply to keep your changes in the form.
Step 7: Save All Changes
The import only changes the form. Nothing is saved yet. Click Save all changes at the bottom of the Custom API page. The CMS asks Are you sure to save your changes? Click Yes. A message confirms Custom APIs saved.
The imported API actions are saved as a draft. They reach real users after you click Publish in the top bar.
Note: If you leave the page or close the browser before Save all changes, the imported APIs are lost and you have to import again.
What Gets Imported
| OpenAPI field | Maps to qlar field |
|---|---|
operationId / summary | Action name |
description | Description |
method | HTTP Method |
servers[0].url + path | Target URI |
parameters | Properties (path, query) |
requestBody | Properties (body) |
Note: The import covers the most common OpenAPI 3.x fields. Some advanced constructs (for example complex
allOf/oneOfschemas or file upload parameters) may not map fully and need manual adjustment after import.
Check the result
-
Test an action. Click
list_projects, then Test API, and click Call API. You should get200 OKand a list with KG-2041, KG-2052 and KG-2063. -
Try it in a conversation. In the preview panel, click the reload button and ask:
Which projects are active right now?Atlas should call
list_projectsand list the three sample projects with their status. Then ask "What is the status of KG-2052?" to confirm that the updatedget_project_statusstill works. -
Refine descriptions. The AI uses the action name and description to decide when to call each API. If an imported description is missing or generic, make it more specific.
Next steps
- Next in the journey: Set authentication, to apply credentials to all imported APIs at once.
- Connect Your API: register a single API action manually and understand all available options.
- Using Plugins: use pre-built integrations instead of configuring raw APIs.