> Source: https://builder.ema.ai/v2/api-reference/integrations-api
> Title: Integrations API

# Integrations API

Tools are how an AI Employee reaches outside the platform — looking up a record in a CRM, filing a ticket, calling an internal API. The Integrations API is the catalog and credential layer behind those Tools: it lists the integrations available to your tenant, installs them, stores their credentials, enables individual functions, registers Model Context Protocol (MCP) servers, and executes a function by name. The integrations service is mounted at `/api/v1/integrations`, so every path below is that prefix plus the path shown.

All requests require a [JWT or tenant API key](/builder/v2/api-reference/authentication), sent as `Authorization: Bearer <token>` or the `X-API-Key` header. Examples use `https://your-tenant.ema.co` as the host.

> [INFO]
> **Catalog, integration, function.** A _catalog entry_ is an integration available to install (Salesforce, Jira, an MCP server, a custom connector). Installing one creates a tenant _integration_ that holds your credentials and enabled functions. A _function_ is a single callable operation on an integration — the unit a workflow invokes as a Tool.

## Catalog

The catalog lists every integration your tenant can install.

-   **List:** `GET /api/v1/integrations/catalog` returns the visible catalog entries, each with its functions.
-   **Get one:** `GET /api/v1/integrations/catalog/{id}`.
-   **Capabilities:** `GET /api/v1/integrations/capabilities` returns the tenant's integration capabilities derived from manifest-backed catalog rows.

```http
GET https://your-tenant.ema.co/api/v1/integrations/catalog
X-API-Key: ema_sk_live_2f9c...redacted
```

Each `CatalogEntryResponse` carries an `id`, `name`, `display_name`, `category`, `scope` (`catalog` or `custom`), and an array of `functions`. Administrators can also author catalog entries with `POST /api/v1/integrations/catalog` and import an OpenAPI spec into a set of Tools with `POST /api/v1/integrations/catalog/import-spec`.

## Installed integrations

Installing a catalog entry creates a tenant integration.

-   **List:** `GET /api/v1/integrations/integrations`.
-   **Install:** `POST /api/v1/integrations/integrations`.
-   **Get / uninstall:** `GET`, `DELETE /api/v1/integrations/integrations/{id}`.

```http
POST https://your-tenant.ema.co/api/v1/integrations/integrations
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "catalog_id": "8c4d...",
  "package": "salesforce"
}
```

The response is `201 Created` with the `TenantIntegrationResponse` — its `id`, `status` (`active`, `disabled`, or `pending`), `enabled_functions`, and flags such as `has_data_source_credentials` and `has_active_connections`. Installing the same integration twice returns `409`.

### Credentials

`PUT /api/v1/integrations/integrations/{id}/credentials` stores credentials for an integration. The `capability` distinguishes credentials used for data-source syncing from those used for agent Tools.

```http
PUT https://your-tenant.ema.co/api/v1/integrations/integrations/8c4d.../credentials
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "capability": "agent_tool",
  "credentials": { "api_key": "..." }
}
```

`capability` is `data_source` or `agent_tool`. A successful update returns `204 No Content`. Credentials are stored encrypted and are never returned by any read endpoint.

### Enable functions

By default an integration's functions are off. Turn one on or off per integration:

-   **Enable:** `POST /api/v1/integrations/integrations/{id}/functions/{name}/enable`.
-   **Disable:** `POST /api/v1/integrations/integrations/{id}/functions/{name}/disable`.

Both return `204 No Content`. The enabled set is reflected in the integration's `enabled_functions`.

### Per-user OAuth connections

Some integrations connect per user rather than per tenant. To start a consent flow, call `POST /api/v1/integrations/integrations/{id}/oauth2/authorize` for an authorization URL, then `POST .../oauth2/callback` to exchange the returned code for tokens. Read or revoke the current user's connection with `GET` / `DELETE /api/v1/integrations/integrations/{id}/connections/me`.

## Execute a function

Once an integration is installed and its function enabled, you can call it directly.

-   **Discover:** `GET /api/v1/integrations/execute/functions` lists the callable functions for your tenant, each with its `input_schema`.
-   **Execute:** `POST /api/v1/integrations/execute` runs a function by `function_id` (preferred) or `function_name`.

```http
POST https://your-tenant.ema.co/api/v1/integrations/execute
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "function_id": "b7c8...",
  "input": { "account_id": "0015g00000XyZ" }
}
```

The response carries the result:

```json
{
  "execution_id": "f1e2...",
  "status": "success",
  "output": { "name": "Acme Corp", "tier": "enterprise" },
  "duration_ms": 412
}
```

`status` is `success` or `error`; on failure, `error` carries the message. An unknown function, or one not installed for your tenant, returns `404`.

### Execution history

Every execution is recorded for auditing.

-   **List:** `GET /api/v1/integrations/executions` — paginated, with optional `integration_id`, `function_id`, `from`, and `to` (RFC 3339) filters.
-   **Get one:** `GET /api/v1/integrations/executions/{id}` returns the full record, including the `logs` blob for script-based executions. A cross-tenant lookup returns `404`.

## MCP servers

You can register Model Context Protocol servers whose tools become available to AI Employees.

-   **List / register:** `GET`, `POST /api/v1/integrations/mcp-servers`.
-   **Get / edit / delete:** `GET`, `PATCH`, `DELETE /api/v1/integrations/mcp-servers/{id}`. Deleting a server with active agent bindings is blocked.
-   **Tools:** `GET /api/v1/integrations/mcp-servers/{id}/tools` lists the cached tools; `POST .../refresh-tools` re-discovers them.
-   **Lifecycle (admin):** `POST .../activate`, `.../disable`, and `.../enable`.

```http
POST https://your-tenant.ema.co/api/v1/integrations/mcp-servers
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "name": "Internal tools",
  "server_url": "https://mcp.acme.internal",
  "transport": "streamable-http",
  "auth_type": "bearer_token",
  "credentials": { "token": "..." }
}
```

A newly registered server starts in `pending_review`; an administrator activates it before its tools can be used. `transport` is `stdio`, `sse`, or `streamable-http`; `auth_type` is `none`, `api_key`, `bearer_token`, `basic_auth`, or `oauth2`. Editing the URL or credentials re-triggers tool discovery.

## What's next

-   [Knowledge & Ingestion API](/builder/v2/api-reference/knowledge-ingestion-api) — connections to data sources for knowledge bases, which the integrations service also surfaces.
-   [Workflow API](/builder/v2/api-reference/workflow-api) — the workflow runs that invoke these functions as Tools.
-   [AI Employee API](/builder/v2/api-reference/ai-employee-api) — attach Tools to the agents inside an AI Employee.