Import an OpenAPI Schema

Instead 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 updates existing ones.

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_status from 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:

Step 1: Open the Import Wizard

On the Custom API page, click Import OpenAPI Schema. The Import OpenAPI Schema window opens. A stepper at the top shows the four steps of the wizard: Schema Setup, Preview, Confirmation and Result.

Step 2: Set Up the Schema

The Schema Setup step has three parts:

1. Schema Format: choose JSON or YAML. For the sample, choose JSON.

2. Upload a JSON / YAML file to fill the editor automatically. Drag kirana-projects-openapi.json onto the drop zone, or click it and select the file. The file name appears with Click to change file below it. When you upload a file, qlar sets Schema Format from its extension (.json, .yaml or .yml). Uploading is optional: you can also paste the schema in the next step.

3. Override Authentication:

   • No — use existing / no authentication (the default): new APIs are imported without authentication, and APIs that already exist keep the authentication they have.
   • Yes — apply custom authentication to all imported APIs: authentication fields appear, and every imported API gets the authentication you enter here.

   The sample API is public, so leave No selected.

Click Next.

Step 3: Check the Schema in the Editor

The Preview step shows the schema in the Paste your OpenAPI schema here 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.

Click Next. qlar converts the schema. If the schema cannot be read, an error message explains why and you stay on this step.

Step 4: Review What Will Change

The Confirmation step shows an Import Preview with two lists:

• New APIs: operations whose name does not exist on this agent yet. For the sample: list_projects.
• Updated APIs: operations with the same name as an API you already have. For the sample: get_project_status.

What "updated" means: for an existing API, the schema's Description, HTTP Method, Target URI and properties replace the current ones. Your Rules, Response Prompt, Loading Text and, unless you chose to override it, its authentication stay as they are. In the sample, get_project_status gets the schema's slightly shorter description. If you prefer your own wording, edit it after the import.

Click Start Import.

Step 5: Close the Result

The Result step confirms Import Successful with Successfully imported 2 APIs (1 new, 1 updated). and a reminder: "You may need to configure authentication before these APIs can be used. Please review your tools and save to apply changes."

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 panel 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 Update API 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 API successfully updated!

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

Note: The import covers the most common OpenAPI 3.x fields. Some advanced constructs (for example complex allOf/oneOf schemas or file upload parameters) may not map fully and need manual adjustment after import.

Check the result

1. Test an action. Click list_projects, then Test API, and click Call API. You should get 200 OK and a list with KG-2041, KG-2052 and KG-2063.

2. 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_projects and list the three sample projects with their status. Then ask "What is the status of KG-2052?" to confirm that the updated get_project_status still works.

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