Find tools for a task | AgentRouter | Developer Documentation

curl -X POST https://api.agentrouter.to/v1/find \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "query": "recent X posts about a company",
  "limit": 5
}'

{
  "object": null,
  "query": "string",
  "match": "exact",
  "tools": [
    {
      "category_ids": [
        "string"
      ],
      "group_ids": [
        "string"
      ],
      "tool_id": "anyapi.twitter.search",
      "title": "string",
      "provider": "string",
      "summary": "string",
      "fit": "exact",
      "matched_terms": [
        "string"
      ],
      "required_inputs": [
        "string"
      ],
      "executable": true,
      "price": {
        "pricing_version": "string",
        "basis": "units",
        "unit": "string",
        "price_multiplier": "string",
        "multiplier_label": "string",
        "free": true,
        "max_per_call_usd": "string",
        "summary": "string",
        "status": "confirmed",
        "unit_price_usd": "string",
        "image_sample": {
          "width": 1,
          "height": 1,
          "usage": "string",
          "usd": "string"
        },
        "image_offer": {
          "percent_off": 1,
          "min_delivered_pixels": 1,
          "ends_at": "2024-01-15T09:30:00Z",
          "sample_usd": "string"
        },
        "image_pricing": {
          "rates": [
            {
              "label": "string",
              "usd_per_image": "string"
            }
          ]
        },
        "video_pricing": {
          "unit": "clip",
          "sample_seconds": 1,
          "sample_usd": "string",
          "rates": [
            {
              "label": "string",
              "usd_per_second": "string",
              "usd_per_clip": "string"
            }
          ],
          "reference_billing": "string"
        }
      },
      "health": {
        "status": "unknown",
        "samples": 1,
        "window_days": 1,
        "success_rate": 0.5,
        "window": {
          "from": "2024-01-15T09:30:00Z",
          "to": "2024-01-15T09:30:00Z",
          "time_basis": "string"
        },
        "computed_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "hints": [
    {
      "code": "string",
      "message": "string",
      "params": {}
    }
  ]
}

Multilingual semantic and keyword search over enabled tools. Returns candidates with a fit label, required inputs, current price summary and observed health. Tools in an outage are hidden unless include_unavailable is true. Free; anonymous callers are allowed.

Authentication

AuthorizationBearer

An AgentRouter API key or an OAuth access token issued to an MCP host or the CLI.

Request

This endpoint expects an object.

querystringRequired1-500 characters

Short task description.

category_idslist of stringsOptional

Match any registered second-level category.

group_idslist of stringsOptional

Match any registered top-level group.

limitintegerOptional1-50Defaults to 10

providerstringOptional

Only tools from this provider id.

tagslist of stringsOptional

Only tools that carry every tag.

include_unavailablebooleanOptionalDefaults to false

Include tools in an outage.

Response

Candidate tools (possibly none)

objectany

querystring

matchenum

Allowed values:

toolslist of objects

hintslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error