API ReferenceTool Router

Patch a tool router session configv3.0

Markdown
PATCH
/api/v3/tool_router/session/{session_id}

Partially updates the configuration of an existing tool router session. Only the fields provided in the request body will be updated. Uses optimistic concurrency control to prevent lost updates. The previous config is stored in config history.

Authorization

x-api-key<token>

Project API key authentication

In: header

Path Parameters

session_idstringRequired

The unique identifier of the tool router session

Format: toolRouterSessionId

Request Body

application/json

toolkitsobject | object

Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive.

auth_configsobject

The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed

connected_accountsobject

Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same user_id as the session.

manage_connectionsnullable object
toolsobject

Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in enable / disable must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.

tagsenum[] | object

Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.

workbenchnullable object
multi_accountnullable object
preloadobject

Preload configuration for Composio tools. Controls which tools appear in session.tools and the MCP server tool list so the agent can call them directly without going through search first. Custom tools use preload on the custom tool/toolkit definition instead. Not supported when multi-account is enabled. Each preloaded tool adds to the agent context window, so keep the list at or under ~20 tools.

experimentalnullable object

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://backend.composio.dev/api/v3/tool_router/session/trs_1a2b3c4d5e6f" \  -H "Content-Type: application/json" \  -d '{}'
{
  "session_id": "trs_1a2b3c4d5e6f",
  "mcp": {
    "type": "http",
    "url": "https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp"
  },
  "tool_router_tools": [
    "string"
  ],
  "config": {
    "user_id": "string",
    "toolkits": {
      "enabled": [
        "string"
      ]
    },
    "auth_configs": {
      "property1": "string",
      "property2": "string"
    },
    "connected_accounts": {
      "property1": "string",
      "property2": "string"
    },
    "all_connected_accounts": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "manage_connections": {
      "enabled": true,
      "callback_url": "http://example.com",
      "enable_wait_for_connections": false,
      "enable_connection_removal": true
    },
    "tools": {
      "property1": {
        "enabled": [
          "string"
        ]
      },
      "property2": {
        "enabled": [
          "string"
        ]
      }
    },
    "tags": {
      "enabled": [
        "readOnlyHint"
      ],
      "disabled": [
        "readOnlyHint"
      ]
    },
    "workbench": {
      "enable": true,
      "proxy_execution_enabled": true
    },
    "multi_account": {
      "enable": true,
      "max_accounts_per_toolkit": 0,
      "require_explicit_selection": true
    },
    "preload": {
      "tools": [
        "string"
      ]
    }
  },
  "config_version": 0,
  "experimental": {
    "assistive_prompt": "string",
    "custom_toolkits": [
      {
        "slug": "string",
        "name": "string",
        "description": "string",
        "tools": [
          {
            "slug": "string",
            "name": "string",
            "description": "string",
            "input_schema": {
              "property1": null,
              "property2": null
            },
            "output_schema": {
              "property1": null,
              "property2": null
            },
            "original_slug": "string"
          }
        ]
      }
    ],
    "custom_tools": [
      {
        "slug": "string",
        "name": "string",
        "description": "string",
        "input_schema": {
          "property1": null,
          "property2": null
        },
        "output_schema": {
          "property1": null,
          "property2": null
        },
        "extends_toolkit": "string",
        "original_slug": "string"
      }
    ]
  },
  "warnings": [
    {
      "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE",
      "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools."
    }
  ]
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}