# APIDirectory: agent quickstart

APIDirectory is an index of 2,648 public APIs. Some of them sell access through
our gateway, so you can get a key and call them without signing up with the
vendor. Searching the index needs no account and no token.

## Connect

MCP endpoint (streamable HTTP, stateless, no auth): https://apidirectory.com/mcp

Claude Code:

    claude mcp add --transport http apidirectory https://apidirectory.com/mcp

Any MCP client:

    {"mcpServers": {"apidirectory": {"type": "http", "url": "https://apidirectory.com/mcp"}}}

## Tools

- `search_apis(query)`: full-text search. Results carry registry metadata
  and, for APIs that sell here, a `marketplace` object.
- `get_api(slug)`: one record, with endpoints parsed from the API's OpenAPI
  spec where we found one.
- `list_categories()`
- `list_marketplace()`: every API you can get a key for here, with prices
  and plans.
- `subscribe_api(slug, email, plan?)`: get a key.

## Find, subscribe, call

1. Find the API with `search_apis` or `list_marketplace`. If
   `marketplace.sells_here` is true, you can get a key here. Read
   `marketplace.plan` for what's included, what a call costs and what happens
   past the limit.
2. Ask your human before you subscribe, and use their email. The key goes
   there, and so do any bills.
3. Call `subscribe_api(slug, email)`. The `status` tells you what happened:
   - `key_issued`: a free plan. The key is in the response and a copy is
     emailed. Store it: we keep only a hash and cannot show it again.
   - `checkout_required`: a paid plan. Give your human the `checkout_url` or
     `storefront_url`. The key is emailed after they pay. You cannot pay on
     their behalf. If the response also has `free_plan`, you can call
     `subscribe_api` again with `plan` set to `free_plan.plan` to get a free
     key now instead: no checkout, and calls stop at the limit.
   - `not_sold_here`: sign up with the provider at `signup_url`.
4. Call `https://gw.apidirectory.com/<slug>/<path>` with the key in the
   `X-API-Key` header.

A key works only for the API it was issued for. Each API you use needs its
own key, and there is one active key per email per API.

## Limits

Responses carry these headers:

- `X-Gw-Remaining`, `X-Gw-Limit`, `X-Gw-Used`: what's left of the plan this
  period, when the plan has a ceiling.
- `X-Gw-Reset`: when the period resets.
- `X-Gw-Cost`: what this call counted.

On HTTP 429, read the JSON body. `quota_exceeded` means the plan's allowance
is used up until `reset`, and `upgrade` points to where the plan can be
changed. `too_many_concurrent` means slow down. Respect `Retry-After`. Stop
and tell your human rather than retrying in a loop.

## APIs that are MCP servers

If `marketplace.mcp_endpoint` is present, that API is itself an MCP server
with one tool per operation. Connect to it with
`Authorization: Bearer <your key>`. A client that cannot send headers can use
`<mcp_endpoint>/k/<your key>` instead; that URL is then as secret as the key.

## Without MCP

Read-only JSON, no key needed:

- `GET https://apidirectory.com/v1/search?q=QUERY`
- `GET https://apidirectory.com/v1/apis?category=SLUG&auth=api-key&spec=1&page=N`
- `GET https://apidirectory.com/v1/apis/SLUG`

Docs index: https://apidirectory.com/llms.txt