> ## Documentation Index
> Fetch the complete documentation index at: https://docs-eos.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom API connectors in the Space

> Create, view, edit and delete REST API connectors on the Workspace Connectors page, from a Swagger/OpenAPI document or by declaring them by hand.

> [!NOTE]
>
> A **REST API connector** turns each operation of a REST API into a tool a Digital Worker can call. You create and manage the Connector on the Workspace **Connectors** page, then attach it to individual Digital Workers and set a permission for each operation on the Digital Worker details page.

## Entry points

| Entry point | Path | Use it to |
| - | - | - |
| Connectors page | Left sidebar → **Connectors** → **Custom Connectors** tab → **Add connector** → **REST API** | Create, view, edit and delete Connectors |
| Empty state | **Custom Connectors** tab with no Connectors yet → **Add connector** button in the middle | Create your first Connector |
| Digital Worker details | **My Digital Workers** → open a Digital Worker → **Build** → **Configuration** panel → **Connectors** section → **+** | Attach a Connector, set permissions, remove it from the Digital Worker |
| Digital Worker connector picker | In the connector picker → **Create connector** → **REST API** | Create a Connector without leaving the Digital Worker |

## Before you start

* **API document**: An OpenAPI 3.x or Swagger 2.0 file in JSON or YAML, up to 2 MB. Without a document, you need the base URL and the list of endpoints to declare by hand.
* **Public base URL**: Addresses that point to the local machine or private IP ranges (for example `localhost` or `169.254.169.254`) are rejected. Use `https` where possible.
* **Credentials**: An API key or token, or the API's OAuth 2.1 details.
* **Limit**: A Connector keeps up to 200 operations. If the document has more, only the first 200 are imported.

## Create a Connector

### Option 1: Import a Swagger/OpenAPI document

**1. Open the Custom Connectors tab**

Click **Connectors** in the left sidebar and select the **Custom Connectors** tab.

![Custom Connectors tab with no Connectors yet](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_empty.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=c6fd8ab04826dc3142e3cd87714f35e8)

**2. Choose Add connector → REST API**

The menu offers **REST API** (import Swagger/OpenAPI or declare by hand) and **MCP server** (connect an MCP server by URL). Choose **REST API**.

![Add connector menu with REST API and MCP server](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_add_menu.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=f3bd15b877798bf19597578c986a7ec0)

**3. Step 1 Source: Provide the document**

On the **Import Swagger/OpenAPI** tab, drop a file into the box or click **Choose file**. You can also paste the content under **Or paste the document**. Click **Continue**.

![Source step with a pasted OpenAPI document](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_source_import.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=8652fd682e262f04359f86da9740b207)

**4. Step 2 Connection: Check the connection details**

The name, **Base URL** and **Authentication** type are filled in from the document and tagged **From the document**. Review them, enter the key **Value** if the API needs one, then click **Continue**. Each field is described in the Connection step field table below.

![Connection step with the base URL and authentication taken from the document](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_connection.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=33291dcd21b652936dfc18f10122181e)

**5. Step 3 Operations: Choose what the Digital Worker can do**

Each operation shows its method, path, risk label, the tool name the Digital Worker will see (for example `demo-orders-api__list_orders`) and its description. Clear the operations you don't need, filter by method, or expand an operation to edit its description and parameters. Click **Create connector**.

![Operations step with 5 operations selected](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_operations.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=643d79c44edd954e28a2c40a10e07a8d)

**6. Check the result**

The message **Connector created with N operations.** appears and the new Connector card shows the **Connected** status.

![New Connector card with the Connected status](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_card.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=137279c67938e017d2dbe58eba3756ae)

> [!TIP]
>
> The Digital Worker reads each operation's description to decide when to call the API. Write descriptions that say what the operation does and when to use it, even if the source document already has a `summary`.

### Option 2: Declare by hand

Use this when the API has no OpenAPI document, or you only want to expose a few endpoints to the Digital Worker.

**1. Select the Declare by hand tab**

In the **Create API connector** dialog, select **Declare by hand** and click **Continue**.

![Declare by hand tab on the Source step](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_source_manual.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=ed96ad3068a74a29e1a41458f2a80a0c)

**2. Enter the connection details**

Enter the **Name** and **Base URL** and choose the **Authentication** type, as in option 1.

**3. Declare each operation**

Fill in **Method**, **Path**, **Name**, **Risk**, **Description**, the parameters and **What it returns**. Click **Add operation** to declare more, then click **Create connector**.

![Form for the get order operation](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_manual_ops.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=04e847392b5a5ece3c821587c3ad4552)

> [!TIP]
>
> Write path parameters as `{order_id}` in the **Path** field. The Console adds a matching parameter in the **Path** location for you.

### Connection step fields

| Field | Required | What it does | Example |
| - | - | - | - |
| **Name** | Yes | Display name of the Connector. Must be unique. It is also the prefix of every tool name | `Demo Orders API` |
| **Base URL** | Yes | Root address. Every operation path is appended to this URL | `https://api.example.com/v1` |
| **Authentication** | Yes | **No authentication**, **API key / Token**, **OAuth 2.1 (Auto)** or **OAuth 2.1 (Manual)** | API key / Token |
| **Sent in** | With API key | Send the key in a **Header** or the **Query** string | Header |
| **Header name** | With API key | Name of the header or query parameter that carries the key | `X-API-Key`, `Authorization` |
| **Value** | With API key | The key or token. Stored encrypted and never shown again | `sk-...` |
| **Test the connection on save** | No | Calls a GET operation with no parameters to confirm the key works | On |
| **Advanced → Description** | No | Short description of the API, shown on the Connector card | Order management API |
| **Advanced → Operation used for the test** | No | The GET operation used for the connection test. Defaults to **Pick automatically** | `list_orders` |

For OAuth 2.1:

| Type | What you enter | Notes |
| - | - | - |
| **OAuth 2.1 (Auto)** | Nothing else | The Console finds the OAuth endpoints from the base URL (RFC 9728, RFC 8414) and registers a client (RFC 7591) |
| **OAuth 2.1 (Manual)** | **Authorize URL**, **Token URL**, **Client ID**. Optional: **Client secret**, **Scopes** (separated by spaces or commas) | For APIs that publish no OAuth metadata or don't allow client registration |

With either OAuth type, a window opens after you save so you can authorize.

### Operations step fields

| Field | Required | What it does | Example |
| - | - | - | - |
| **Method** | Yes | `GET`, `POST`, `PUT`, `PATCH` or `DELETE` | `GET` |
| **Path** | Yes | Path appended to the Base URL. Write path parameters as `{id}` | `/orders/{order_id}` |
| **Name** | Yes | Tool name. The Digital Worker sees it as `connector-name__name` | `get_order` |
| **Risk** | Yes | **Read-only**, **Writes data** or **Can destroy data**. Sets the default permission when the Connector is attached to a Digital Worker | Read-only |
| **Description** | Recommended | The Digital Worker uses it to decide when to call the operation | Get the details of one order by its ID. |
| **Parameters** | No | Each parameter has a name, a location (**Path**, **Query**, **Header**, **Body field (JSON)**, **Whole body (JSON)**, **Form field**), a type, a description and a **Required** checkbox. Edit as a **Table** or as **JSON** | `order_id`, Path, string |
| **What it returns** | No | Describes the data the API returns, up to 1000 characters | Order status, total and customer name. |

When you import a document, the risk is suggested from the method: `GET` is **Read-only**, `POST`/`PUT`/`PATCH` is **Writes data** and `DELETE` is **Can destroy data**. You can change it when you expand the operation.

## View your Connectors

The **Custom Connectors** tab shows how many Connectors you have and one card per Connector:

* The Connector **name** and **description**.
* The **status**, for example **Connected**.
* The **number of operations** and where it came from (**OpenAPI** when imported from a document).
* A **trash** icon to delete it and a **Manage** button to edit it.

Use **Search custom connectors...** to filter by name when the list grows.

## Edit a Connector

Click **Manage** on the card to open the **Edit API connector** dialog. It has three tabs: **Source**, **Connection** and **Operations**. Click **Save changes** when you're done. The message **Connector updated.** appears.

### Change the connection details

On the **Connection** tab you can change the name, the Base URL and the authentication type. A saved key shows as **•••• saved**. Click **Replace key** to enter a new one.

![Connection tab in the Edit API connector dialog](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_edit_connection.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=2b4d03e1af9e0a09f414359684e23a8d)

If you change the Base URL or the authentication type, the Console warns that every existing connection will be disconnected and must be reconnected.

![Warning shown after changing the address or authentication](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_auth_warning.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=cbd5383a115d27241fcdbd515f94368a)

### Re-import the document when the API changes

**1. Paste the new version of the document**

On the **Source** tab, drop the new file or paste the new content.

![Source tab with version 1.1.0 of the document](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_reimport.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=ad3f303ae0cd3034772f8e7f22357bce)

**2. Review the Operations tab**

Open the **Operations** tab to see the list after the import and select the operations you want.

![Operations tab after re-import, with a new refund operation](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_reimport_operations.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=7a5951279e41e848106dc293455fb529)

**3. Save the changes**

Click **Save changes**. The operation count on the Connector card updates.

> [!WARNING]
>
> Importing again **replaces the whole operation list** with the new document. Operations that were removed or renamed in the new document are no longer available to Digital Workers that use this Connector. After saving, open those Digital Workers to check each operation's permission and run a test again.

If you click **Cancel** with unsaved changes, the Console asks **Discard changes?**. Choose **Discard** to leave or **Keep editing** to go back.

## Delete a Connector

**1. Click the trash icon on the Connector card**

A confirmation dialog opens.

![Confirmation dialog for deleting a Connector](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/en_custom_api_delete.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=da24230f2a7120dd638d039ab06d16e4)

**2. Click Delete connector**

The message **Connector deleted.** appears. The Connector is removed from every Digital Worker that used it.

> [!WARNING]
>
> Deleting a Connector **cannot be undone**. Digital Workers that use its operations lose access immediately. The dialog doesn't list which Digital Workers are affected, so check before you delete.

> [!NOTE]
>
> Connectors have no paused state. To stop one temporarily for a Digital Worker, remove it from that Digital Worker or set its operations to **Block**.

Once the Connector is created, attach it to a Digital Worker as described in [Use Custom APIs in a Digital Worker](https://docs-eos.fpt.ai/eos/en/agent-custom-api-connectors.md).

## Troubleshooting

| What you see | Cause | Fix |
| - | - | - |
| A message that a connector with this name already exists | The name is already used by another Connector | Change the name on the Connection step |
| A message that the base URL must be a public address when you click Create connector | The Base URL points to the local machine or a private IP | Use the API's public address |
| Only 200 operations are imported | The document has more than 200 operations | Split the document into several Connectors by business area |
| The document can't be read | Invalid JSON/YAML, or not an OpenAPI/Swagger document | Check the document with an OpenAPI validator and import it again |
| Tool names look odd, for example `api-n-h-ng-demo__...` | The Connector name has accented characters, which are replaced with `-` | Use a plain ASCII name such as `Orders API` |

## See also

> **[Use Custom APIs in a Digital Worker](https://docs-eos.fpt.ai/eos/en/agent-custom-api-connectors.md)**
>
> Attach the Connector to a Digital Worker, set permissions and test it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.