# List tools

`GET /v1/tools`

No API key needed. Without one, requests are limited per IP address. A key sent must be valid.

List the tools in the catalog, ordered by platform and then by tool.

Each tool names the providers that can serve it and the lowest price of one call among them: what one call costs you. A tool with `callable: false` is listed but cannot be called yet. Filter by `platform`, `category` or `callable`.

No API key is needed. Without one, requests are rate limited per IP address.

## Example request

cURL:

```bash
curl "https://api.voxoria.ai/v1/tools?callable=true"
```

Python:

```python
import httpx

response = httpx.get(
    "https://api.voxoria.ai/v1/tools",
    params={"callable": True},
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools?callable=true");
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "list_tools",
  "arguments": {
    "callable": true
  }
}
```

## Query parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `platform` | string | No |  | Only tools on this platform, by its `slug`. |
| `category` | string | No |  | Only tools of this category. One of `seo`, `social`, `enrichment`, `reviews`. |
| `callable` | boolean | No |  | Only tools that can be called today (`true`) or that cannot yet (`false`). |

## Response

### 200

Every tool that matches the filters.

The body is a JSON array. Each item has these fields.

A tool as the catalog lists it.

`providers` are the providers that can serve it. `from_price_usd` is what one call costs you at the cheapest of them, null when there are none. A provider priced by results counts at its `max_price_usd`.

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| `tool` | string | No | The tool's ID, as calls and quotes take it. |
| `name` | string | No | The tool's name. |
| `platform` | object | No | The platform the tool's data is about. |
| `platform.slug` | string | No | The platform's ID, as the `platform` filter takes it. |
| `platform.name` | string | No | The platform's name. |
| `category` | string | No | The kind of data it returns. One of `seo`, `social`, `enrichment`, `reviews`. |
| `callable` | boolean | No | Whether the tool can be called today. |
| `from_price_usd` | string | Yes | What one call costs at the cheapest provider. Null when no provider can serve it. |
| `providers` | array of string | No | The IDs of the providers that can serve it. |

### Example 200 response

```json
[
  {
    "tool": "google.serp.organic",
    "name": "Search Google organic results",
    "platform": {
      "slug": "google",
      "name": "Google"
    },
    "category": "seo",
    "callable": true,
    "from_price_usd": "0.0214",
    "providers": [
      "example-provider",
      "another-provider"
    ]
  }
]
```

## Errors

| Status | Body | Description |
| --- | --- | --- |
| 400 | [Refused request](/docs/call-response.md#refused-request) | The request was refused. |
| 401 | [Refused request](/docs/call-response.md#refused-request) | An API key was sent and is wrong or revoked (`INVALID_AUTH_TOKEN`). |
| 422 | [Invalid request](/docs/call-response.md#invalid-request) | The request is not valid (`VALIDATION`). |
| 429 | [Refused request](/docs/call-response.md#refused-request) | Too many requests without an API key from this IP address, or with this API key (`RATE_LIMITED`). |