The catalog is the routing table for everything 1ToolRing sells. It is public reference data: no key, no credits. Every entry it lists is callable and priced; nothing is listed that is not.

Base URL: `https://api.1toolring.com/api/v1/catalog`

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/catalog` | Summary: categories, capabilities, sources, and `total`. |
| GET | `/catalog/search?q=` | Search entries by job. Optional `category`, `capability`, `limit` (1 to 100, default 20). An empty `q` browses everything. |
| GET | `/catalog/{id}` | One entry in full. |
| GET | `/capabilities` | The jobs, their sources and adapters. `?routed=1` lists only routable jobs. |

## Search

```bash
curl "https://api.1toolring.com/api/v1/catalog/search?q=email&limit=3"
```

```json
{
  "data": {
    "results": [
      {
        "id": "email.verify",
        "name": "Verify one email",
        "summary": "Real-time deliverability verdict for one address, with a 7-day result cache (cache hits are free)",
        "category": "Email",
        "method": "POST",
        "path": "/api/v1/email/verify",
        "price_credits": 105,
        "price_unit": "chargeable address",
        "capability": "email.verify",
        "source": "millionverifier",
        "freshness": { "live": true, "max_age_seconds": 0 },
        "verified_at": "2026-10-01"
      }
    ]
  }
}
```

## Read an entry before you spend

```bash
curl https://api.1toolring.com/api/v1/catalog/email.verify
```

| Field | Meaning |
| --- | --- |
| `price_credits` | The price of one billable hit, in credits (1 credit = Rp1). |
| `price_unit` | What one billable hit is, for example `chargeable address`. |
| `cost` | Where the price comes from, when it was checked, and the confidence. |
| `freshness` | `{live, max_age_seconds, note}`: how old the answer may be. |
| `verified_at` | When the entry was last checked against the registry. |
| `example` | A curl command ready to copy. |

An entry whose price carries no provenance is refused with `409 CATALOG_PRICE_UNVERIFIED` rather than shown as free.

## Categories today

| Category | Entries | Source |
| --- | --- | --- |
| Email | Verify one address, bulk jobs, job status, report, cancel, credits | MillionVerifier, checked live per address |

The live counts come from `GET /catalog`; read them from the API, not from this page.

## Routed calls

A capability with more than one source can be called by job instead of by endpoint:

```text
POST https://api.1toolring.com/api/v1/toolring/<capability>
```

The router picks the source, reports it in `X-ToolRing-Route` and `X-ToolRing-Source`, and charges the price of the endpoint that answered. Failover is attempted only after a failed hit, and a failed hit is refunded, so a failover never doubles a charge. No capability is routable today; `GET /capabilities?routed=1` is the honest list.