Agent Connection Tools API

These endpoints manage which connection-instance tools are enabled for a specific AI agent. All paths are under the /ai prefix.

For a conceptual overview of how connection tools work, see AI Connection Tools (Per Instance).

Authentication

Both endpoints require:

A valid Authorization: Bearer <jwt> token
A valid x-org-id header (or the orgId embedded in the JWT)
A CASL policy that allows read/update on the ai.agent subject

The JWT's agencyId and userId must correspond to a user who has visibility into the connections being referenced. Connections not accessible to the calling user are excluded from catalog responses and rejected in upsert requests.

GET /ai/agents/:agentId/connection-tools/catalog

Returns the list of connections accessible to the calling user in the org, their available tools (organized by provider type), and the currently enabled tools for each connection on this agent.

Path Parameters

Parameter	Type	Description
`agentId`	UUID v7	The AI agent's identifier

Response — 200 OK

json

{
  "connections": [
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000010",
      "name": "Work Gmail",
      "slug": "work-gmail",
      "provider": "google_gmail",
      "status": "active",
      "tools": [
        { "name": "send_gmail_message",  "description": "Send a Gmail message." },
        { "name": "list_gmail_messages", "description": "List Gmail messages." }
      ],
      "enabledTools": ["send_gmail_message"]
    },
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000011",
      "name": "Agency Workspace",
      "slug": "agency-workspace",
      "provider": "google_workspace",
      "status": "active",
      "capabilities": [
        {
          "key": "gmail",
          "tools": [
            { "name": "send_gmail_message",  "description": "Send a Gmail message." },
            { "name": "list_gmail_messages", "description": "List Gmail messages." }
          ]
        },
        {
          "key": "sheets",
          "tools": [
            { "name": "list_spreadsheets",       "description": "List Google Sheets." },
            { "name": "read_spreadsheet_values",  "description": "Read values from a range." }
          ]
        },
        {
          "key": "calendar",
          "tools": [
            { "name": "list_calendar_events",  "description": "List calendar events." },
            { "name": "create_calendar_event", "description": "Create a calendar event." }
          ]
        }
      ],
      "enabledTools": ["send_gmail_message", "list_calendar_events"]
    }
  ]
}

Response fields per connection entry:

Field	Type	Notes
`connectionId`	UUID v7	Connection identifier
`name`	string	Human-readable connection name
`slug`	string	Kebab slug used to namespace tools in the LLM tool set (e.g. `work-gmail`)
`provider`	string	Provider key: `smtp`, `telegram`, `google_gmail`, `google_workspace`
`status`	string	`active`, `error`, or `disconnected`
`tools`	array	For non-`google_workspace` providers: flat list of available tool descriptors
`capabilities`	array	For `google_workspace` only: tool descriptors grouped by capability (`gmail`, `sheets`, `calendar`)
`enabledTools`	string[]	Tool names currently granted for this connection on this agent. `[]` when nothing is enabled.

Only one of tools or capabilities will be present, depending on provider.

Errors

Status	When
401	Missing or invalid JWT
403	Caller cannot `read` the `ai.agent` subject
404	Agent not found in the org

Example

bash

curl -X GET \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/connection-tools/catalog" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002"

PUT /ai/agents/:agentId/connection-tools

Replaces the full set of connection-tool grants for an agent. This is a full-diff replace — the payload represents the complete desired state. Any connection not included in grants will have all its tools disabled.

To disable all tools for all connections, send { "grants": [] }.

Path Parameters

Parameter	Type	Description
`agentId`	UUID v7	The AI agent's identifier

Request Body

json

{
  "grants": [
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000010",
      "enabledTools": ["send_gmail_message"]
    },
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000011",
      "enabledTools": ["send_gmail_message", "list_calendar_events"]
    }
  ]
}

Field	Type	Constraints	Description
`grants`	array	max 64 items	Full desired grant set. Empty array removes all grants.
`grants[].connectionId`	UUID v7	required	Must be a connection accessible to the calling user in the org
`grants[].enabledTools`	string[]	min 1, max 64 items	Tool names from the provider's catalog. Must be valid for the connection's provider type.

Response — 200 OK

json

{
  "agentId": "01927f3e-0000-7000-8000-000000000001",
  "grants": [
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000010",
      "enabledTools": ["send_gmail_message"]
    },
    {
      "connectionId": "01927f3e-0000-7000-8000-000000000011",
      "enabledTools": ["send_gmail_message", "list_calendar_events"]
    }
  ]
}

The response echoes the persisted state. Slugs are not included in the upsert response — use GET catalog to retrieve slugs.

Errors

Status	Code	When
400	`AI.EMPTY_ENABLED_TOOLS_FOR_CONNECTION`	A grant entry has `enabledTools: []`. Use an absent entry to remove a connection's grant.
400	`AI.INVALID_CONNECTION_TOOL_NAMES`	One or more tool names are not valid for the connection's provider type
400	`AI.DUPLICATE_CONNECTION_IDS`	The same `connectionId` appears more than once in `grants`
401	—	Missing or invalid JWT
403	—	Caller cannot `update` the `ai.agent` subject, or a referenced connection is not accessible
404	`AI.AGENT_NOT_FOUND`	Agent not found in the org
422	—	Request body fails Zod validation (e.g. invalid UUID format)

Example — grant two connections

bash

curl -X PUT \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/connection-tools" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": [
      { "connectionId": "01927f3e-0000-7000-8000-000000000010", "enabledTools": ["send_gmail_message"] }
    ]
  }'

Example — remove all connection-tool grants

bash

curl -X PUT \
  "https://api.daramex.app/ai/agents/01927f3e-0000-7000-8000-000000000001/connection-tools" \
  -H "Authorization: Bearer <jwt>" \
  -H "x-org-id: 01927f3e-0000-7000-8000-000000000002" \
  -H "Content-Type: application/json" \
  -d '{ "grants": [] }'

Example — 400 invalid tool name for provider

bash

# Request — send_telegram_message is not valid for a google_gmail connection
curl -X PUT ... -d '{
  "grants": [
    { "connectionId": "01927f3e-0000-7000-8000-000000000010",
      "enabledTools": ["send_telegram_message"] }
  ]
}'

# Response 400
{
  "statusCode": 400,
  "code": "AI.INVALID_CONNECTION_TOOL_NAMES",
  "message": "Some tool names are not valid for this connection's provider",
  "details": {
    "connectionId": "01927f3e-0000-7000-8000-000000000010",
    "invalidTools": ["send_telegram_message"]
  }
}

Agent Connection Tools API ​

Authentication ​

GET /ai/agents/:agentId/connection-tools/catalog ​

Path Parameters ​

Response — 200 OK ​

Errors ​

Example ​

PUT /ai/agents/:agentId/connection-tools ​

Path Parameters ​

Request Body ​

Response — 200 OK ​

Errors ​

Example — grant two connections ​

Example — remove all connection-tool grants ​

Example — 400 invalid tool name for provider ​

Agent Connection Tools API

Authentication

GET /ai/agents/:agentId/connection-tools/catalog

Path Parameters

Response — 200 OK

Errors

Example

PUT /ai/agents/:agentId/connection-tools

Path Parameters

Request Body

Response — 200 OK

Errors

Example — grant two connections

Example — remove all connection-tool grants

Example — 400 invalid tool name for provider