COcomposiohq
Tool Router

Search for tools using a query

Changed on

Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.

post/api/v3/tool_router/session/{session_id}/search

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3/tool_router/session/{session_id}/search
  • Auth
    API key in header x-api-key

Path parameters

session_idstring toolRouterSessionId required

Tool router session ID (trs_*)

Example:trs_LX9uJKBinWWr

Request body

modelstring

Optional model hint for search/planning behavior (e.g., "gpt-4o"). Ignored if invalid.

search_strategy'auto' | 'tool_search'

Search path to use. Defaults to auto. Use tool_search to bypass cached plans and run direct tool search.

Example request

{
  "queries": [
    {
      "use_case": "Send a slack message to a channel"
    }
  ],
  "model": "gpt-4o",
  "search_strategy": "tool_search"
}

Response

Successfully executed the search. Returns matching tool slugs, schemas, connection statuses, and guidance.

successboolean required

Whether all searches completed successfully. False if any query failed.

errorstring nullable required

Error message if any searches failed, null if all succeeded. Format: "X out of Y searches failed, reasons: <details>"

tool_schemasobject required

Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries.

next_steps_guidancestring[] required

Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction.

Changes