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, sent as Authorization: Bearer <token> or the X-API-Key header. Examples use https://your-tenant.ema.co as the host.

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.

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

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.

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.

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:

{
  "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.

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 — connections to data sources for knowledge bases, which the integrations service also surfaces.
• Workflow API — the workflow runs that invoke these functions as Tools.
• AI Employee API — attach Tools to the agents inside an AI Employee.