# OpenAPI

### Connector Creation and Identification

The Connector is created in the Administration Portal (**Artifacts > Connectors**).

* Click **"Create"** and select the type **"OpenAPI Connector"**.

<figure><img src="/files/NieBCxjdCgujuueoCzcQ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/7S5hlbGdHKjLkGckoIDv" alt=""><figcaption></figcaption></figure>

* Select your Power Omni **Project**.
* **Name:** Internal identifier for management in the panel. Use clear names such as “Inventory Management API” or “CRM Integration”.
* **Description:** This field is read by the Artificial Intelligence. Provide a detailed description of what this connector does.
  * **Tip:** The better the description, the more accurately the AI will decide to use this tool during a conversation.

***

### Authentication (Security)

For Power Omni to access external data, it must securely identify itself to the target API.

* **Authentication Type:**

  * **Anonymous (No Authentication):** Used only for APIs that do not require access keys.

  <figure><img src="/files/vSMG0L0LOWKUzsfmQqJz" alt=""><figcaption></figcaption></figure>

  * **API Key:** You define the Header — usually `X-API-KEY` or `Authorization` — and enter the key value.

  <figure><img src="/files/DVN11i5hqNI0W7avck3k" alt=""><figcaption></figcaption></figure>

  <figure><img src="/files/IcCwajsfhNnzjkIg4wMw" alt=""><figcaption></figcaption></figure>
* **Import Existing Connection:** Use this option if you have previously created the connection and want to reuse it.

<figure><img src="/files/hrgtEdS8iY6gqsWNOHss" alt=""><figcaption></figcaption></figure>

* **Create New Connection:** Use this if it is your first time configuring the API.

<figure><img src="/files/QAvJRAG58RIFhrTga1vq" alt=""><figcaption></figcaption></figure>

***

### Schema Definition (OpenAPI)

The Schema is the technical map of the API. It tells the AI which “doors” (endpoints) are available, what information it must send, and what it will receive in return.

#### Automatic Import Method (Via URL)

* **Specification URL:** In this field, enter the direct link to the API specification file (Ex: <https://api.yourcompany.com/v1/swagger.json>).
* **Fetch Specification Button:** When clicked, Power Omni automatically retrieves the OpenAPI specification.

<figure><img src="/files/l2e3d5vB6v0szB9775HY" alt=""><figcaption></figcaption></figure>

#### Manual Import Method

* **How to Use:** Copy the content of your OpenAPI specification and paste it directly into the editor.
* **Schema Editor (JSON):** Area to paste the OpenAPI specification code.

<figure><img src="/files/vqZwzrg62iRxngfYHQ61" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/WLs0l2IkViSLd8WHWSb4" alt=""><figcaption></figcaption></figure>

* **Endpoints and Methods:** The schema must detail supported methods, such as:
  * `GET`: To retrieve information.
  * `POST`: To create new records.
  * `PUT/PATCH`: To update existing data.
* **Input Parameters:** Defines which data the AI must extract from the user’s conversation to populate the request (Ex: order\_id, customer\_cpf).
* **Validation:** The system will validate the JSON structure to ensure the format follows OpenAPI 3.0 standards.

<figure><img src="/files/O4fZQaNlIUGfLoU4U6cw" alt=""><figcaption></figcaption></figure>

***

### Validation&#x20;

After configuring the structure and security, the connector must be registered to become available to Agents.

* The system performs a final syntax check on the Schema. If there are formatting errors in the JSON, the system will indicate the error line for correction.
* Click **Save**.

### Final Step: Linking the Connector to the Agent

The Agent will only have access to the API functions after the relationship is configured.

* Go to **Artifacts > Agents** in the Administration Portal.
* Select the AI Agent that needs to interact with the API.
* Navigate to the **Relationships > Connectors** tab or section.
* In the list of available Connectors, locate the newly created OpenAPI Connector.
* Associate the Connector with the Agent.
* Click **"Save"** to apply the changes.

***

### ✅ Best Practices and Governance

* When generating an API Key in your external system, grant permission only for the necessary methods. Example: If the AI only needs to retrieve data, do not provide a key with DELETE permissions.
* **Error Handling:** Ensure your external API returns clear error messages (Ex: “Order not found”). The AI will read this message and be able to explain to the end user what happened.
* **Updated Documentation:** Whenever your external API changes (for example, adding a new required field), remember to update the Schema on this screen to avoid integration failures.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.poweromni.ai/en/administration-and-configuration/artifacts/connectors/openapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.