Skip to main content

​
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

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

​
Response

Returns an array of catalog items.
​
id
string
Unique catalog identifier, e.g. github, slack.
​
name
string
Human-readable integration name.
​
icon
string
Icon identifier or URL.
​
category
string
Integration category.
​
description
string
Short description of what the integration does.
​
auth_type
string
Authentication mechanism required: token, oauth, apikey, etc.
​
config_schema
object
JSON Schema describing the optional config object for this integration.
​
enabled
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

​
catalogId
string
required
Catalog entry ID, e.g. slack, github.
curl http://localhost:8080/api/integrations/catalog/slack \
  -H "Authorization: Bearer $TOKEN"
StatusCondition
404Catalog item not found

​
List agent integrations

Return all integrations connected to a specific agent. 
GET /agents/:id/integrations

​
Path parameters

​
id
string
required
Agent UUID.

​
Response

​
id
string
Integration record UUID.
​
agent_id
string
Agent UUID.
​
provider
string
Integration provider identifier.
​
catalog_id
string
Catalog entry this integration maps to.
​
config
object
Provider-specific configuration (non-sensitive).
​
status
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

​
servers
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

​
providers
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

​
id
string
required
Agent UUID.

​
Request body

​
provider
string
required
Integration provider identifier. Must exist in the catalog.
​
token
string
API token or access token for the integration. Required for token and apikey auth types.
​
config
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"
}
StatusCondition
400Missing 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

​
id
string
required
Agent UUID.
​
iid
string
required
Integration record UUID.

​
Response

​
success
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

​
id
string
required
Agent UUID.
​
iid
string
required
Integration record UUID.

​
Response

​
success
boolean
true when the connection test passed.
​
message
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

​
channelId
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

​
received
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 }
StatusCondition
400Channel not found or payload rejected by the channel handler