Integrations API: connect tools to agents

Browse the integration catalog, connect third-party tools to Nora agents, test connections, and receive inbound webhook events from external services.

The Integrations API connects external tools and services to your agent runtimes. You browse a catalog of available integrations, attach them to specific agents with their credentials, and verify that the connection works. When a token or config changes, Nora pushes the updated values to the running agent in the background. You can also expose a public webhook URL that external services POST events to.

After you connect an integration, Nora automatically syncs the credentials to the agent runtime and, where relevant, updates environment variables in the live gateway process. You do not need to restart the agent.

List integration catalog

Return all available integrations. Optionally filter by category.

GET /integrations/catalog

Query parameters

string

Filter by category, e.g. storage, communication, data. When omitted, all categories are returned.

Response

Returns an array of catalog items.

string

Unique catalog identifier, e.g. github, slack.

string

Human-readable integration name.

string

Icon identifier or URL.

string

Integration category.

string

Short description of what the integration does.

string

Authentication mechanism required: token, oauth, apikey, etc.

object

JSON Schema describing the optional config object for this integration.

boolean

Whether the integration is available for connection.

curl "http://localhost:8080/api/integrations/catalog?category=communication" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "slack",
    "name": "Slack",
    "icon": "slack",
    "category": "communication",
    "description": "Send and receive messages through Slack channels.",
    "auth_type": "token",
    "config_schema": { "type": "object", "properties": { "channel": { "type": "string" } } },
    "enabled": true
  }
]

Get catalog item

Fetch the full detail for a single integration catalog entry.

GET /integrations/catalog/:catalogId

Path parameters

string

required

Catalog entry ID, e.g. slack, github.

curl http://localhost:8080/api/integrations/catalog/slack \
  -H "Authorization: Bearer $TOKEN"

Status	Condition
`404`	Catalog item not found

List agent integrations

Return all integrations connected to a specific agent.

GET /agents/:id/integrations

Path parameters

string

required

Agent UUID.

Response

string

Integration record UUID.

string

Agent UUID.

string

Integration provider identifier.

string

Catalog entry this integration maps to.

object

Provider-specific configuration (non-sensitive).

string

Connection status, e.g. active.

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": "slack",
    "catalog_id": "slack",
    "config": { "channel": "#alerts" },
    "status": "active"
  }
]

List per-agent MCP servers

List the Model Context Protocol servers available to an agent. Each supported provider is annotated with whether the agent has the integration connected (connected) and whether the server is enabled (enabled). Requires the integrations:read scope.

GET /agents/:id/mcp-servers

Response

array

One entry per supported provider, each with provider, name, npmPackage, docsUrl, notes, connected, and enabled.

{
  "servers": [
    {
      "provider": "gitlab",
      "name": "GitLab",
      "npmPackage": "@modelcontextprotocol/server-gitlab",
      "docsUrl": "https://github.com/modelcontextprotocol/servers/tree/main/src/gitlab",
      "notes": "Reference MCP server.",
      "connected": true,
      "enabled": false
    }
  ]
}

Set enabled MCP servers

Replace the set of enabled MCP servers for an agent. Only providers with a connected integration take effect; unknown providers are ignored. The change is applied to the runtime on the agent’s next redeploy. Requires the integrations:write scope.

PUT /agents/:id/mcp-servers

Body

string[]

required

Provider ids to enable, e.g. ["gitlab", "notion"].

{
  "enabled": ["gitlab"],
  "redeployRequired": true,
  "servers": [{ "provider": "gitlab", "connected": true, "enabled": true }]
}

Connect an integration

Attach a third-party integration to an agent. The credentials are encrypted and synced to the agent runtime immediately.

POST /agents/:id/integrations

Path parameters

string

required

Agent UUID.

Request body

string

required

Integration provider identifier. Must exist in the catalog.

string

API token or access token for the integration. Required for token and apikey auth types.

object

Provider-specific configuration. Structure is defined by the catalog item’s config_schema.

Response

Returns the created integration record. Tokens are not included in the response.

curl -X POST http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"slack","token":"xoxb-your-slack-bot-token","config":{"channel":"#alerts"}}'

{
  "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "slack",
  "catalog_id": "slack",
  "config": { "channel": "#alerts" },
  "status": "active"
}

Status	Condition
`400`	Missing `provider`

Remove an integration

Disconnect an integration from an agent. The credentials are purged from the agent runtime on the next sync.

DELETE /agents/:id/integrations/:iid

Path parameters

string

required

Agent UUID.

string

required

Integration record UUID.

Response

boolean

true when the integration was removed.

curl -X DELETE \
  http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/c3d4e5f6-a7b8-9012-cdef-234567890123 \
  -H "Authorization: Bearer $TOKEN"

{ "success": true }

Test an integration

Verify that a connected integration can reach the remote service. Returns the test result without modifying any data.

POST /agents/:id/integrations/:iid/test

Path parameters

string

required

Agent UUID.

string

required

Integration record UUID.

Response

boolean

true when the connection test passed.

string

Human-readable result description.

curl -X POST \
  http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/c3d4e5f6-a7b8-9012-cdef-234567890123/test \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Connection verified successfully"
}

Inbound webhook receiver

Receive events from external services that do not support OAuth callbacks. This endpoint is public — no authentication is required. You configure the external service to POST to this URL.

POST /webhooks/:channelId

Path parameters

string

required

The UUID of the Nora channel that should handle the inbound event. Obtain this from GET /agents/:id/channels.

The request body can be any JSON payload from the external service. Headers are forwarded to the channel handler for signature verification.

Response

boolean

true when the webhook was accepted.

curl -X POST http://localhost:8080/api/webhooks/d5e6f7a8-b9c0-1234-defa-123456789012 \
  -H "Content-Type: application/json" \
  -d '{"event":"push","ref":"refs/heads/main"}'

{ "received": true }

Status	Condition
`400`	Channel not found or payload rejected by the channel handler

Getting started

Concepts

Configuration

Guides

API Reference

Support

Integrations

Integrations API: connect tools to agents

List integration catalog

Query parameters

Response

Get catalog item

Path parameters

List agent integrations

Path parameters

Response

List per-agent MCP servers

Response

Set enabled MCP servers

Body

Connect an integration

Path parameters

Request body

Response

Remove an integration

Path parameters

Response

Test an integration

Path parameters

Response

Inbound webhook receiver

Path parameters

Response

​Integrations API: connect tools to agents

​List integration catalog

​Query parameters

​Response

​Get catalog item

​Path parameters

​List agent integrations

​Path parameters

​Response

​List per-agent MCP servers

​Response

​Set enabled MCP servers

​Body

​Connect an integration

​Path parameters

​Request body

​Response

​Remove an integration

​Path parameters

​Response

​Test an integration

​Path parameters

​Response

​Inbound webhook receiver

​Path parameters

​Response

Integrations API: connect tools to agents

List integration catalog

Query parameters

Response

Get catalog item

Path parameters

List agent integrations

Path parameters

Response

List per-agent MCP servers

Response

Set enabled MCP servers

Body

Connect an integration

Path parameters

Request body

Response

Remove an integration

Path parameters

Response

Test an integration

Path parameters

Response

Inbound webhook receiver

Path parameters

Response