Import an OpenAPI Schema

Open in CMS

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 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_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:

operationIdRequestWhat it returns
get_project_statusGET /projects/{projectCode}.jsonStatus, progress, budget and current approval stage of one project
list_projectsGET /projects/index.jsonCodes, 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.

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

  2. Optional file upload: the drop area reads Drop a JSON or YAML file here and has a Choose file button. Drag kirana-projects-openapi.json onto 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, .yaml or .yml). Uploading is optional: you can also paste the schema in the next step.

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

Import OpenAPI schema drawer on the Upload step (step 1 of 4) with the file kirana-projects-openapi.json and Replace and Remove, Schema format JSON selected, and Authentication for the imported APIs set to Keep what each API has now, or none for a new API

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.

Edit step (step 2 of 4) with the OpenAPI schema editor showing the Kirana Projects API (sample) JSON: openapi 3.0.3, the info block, the servers URL https://app-asset.qlar.ai/docs-media/samples/kirana-api and the start of the /projects/{projectCode}.json path with operationId get_project_status, and the buttons Back and Next

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.

Review step (step 3 of 4) with What the import changes, the notice Replaced APIs take the schema fields, and a table with list_projects marked New and get_project_status marked Replaced, each with Method GET and its endpoint, and the buttons Back and Import 2 APIs

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

Done step (step 4 of 4) with a green check, Import complete, the message Imported 2 APIs (1 new, 1 replaced). Check their authentication, then save the page to keep them., and the Close button

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 fieldMaps to qlar field
operationId / summaryAction name
descriptionDescription
methodHTTP Method
servers[0].url + pathTarget URI
parametersProperties (path, query)
requestBodyProperties (body)

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.