> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# Agent API

> Four read-only routes: search the endpoint catalog by keyword, read the exact amount a call debits, fetch a ready-to-send request, and check a key's balance.

Three small, public, read-only routes and one account route let an agent choose and price a call before it spends anything. They are generated from the same code that mounts and bills every proxy, so a price shown here is the amount the ledger debits.

#### Install the skill (optional)

Tell your agent `set up https://nativeport.ai/SKILL.md`. The file is generated by the gateway and carries the workflow below, the key hand-off, and one table row per endpoint family. Prefer MCP? The same four operations are tools on `https://api.nativeport.ai/mcp` — see [Set up with MCP](/mcp). From a shell, `npx nativeport@latest` wraps the same calls — see [Set up with CLI](/cli).

#### Find

`GET https://api.nativeport.ai/v1/catalog?q=google%20search` ranks entries by how many keywords they match, then by expected price. Omit `q` for the whole catalog (about forty entries).

#### Inspect

`GET https://api.nativeport.ai/v1/catalog/serper` returns the entry plus a `request` object (method, URL, headers, body) and its `curl`.

#### Call natively

Send that request with your bearer. The response is the provider's own. When cost matters, read `GET /v1/account` before and after.

## `GET /v1/catalog`

Public. Cached for five minutes with a strong `ETag` (`If-None-Match` answers `304`).

| Query   | Meaning                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| `q`     | Two or three English keywords. Tokens of four or more characters also match by prefix (`scrap` finds `scrape`). |
| `limit` | Results to return when `q` is set. Default 10, maximum 50.                                                      |

Each entry carries `id`, `provider`, `group`, `methods`, `route`, `actions` (wildcard families only), `summary`, `tags`, `capabilities`, `example`, `price`, `priceLabel`, `expectedMicro`, `restrictions` and `docUrl`. With `q`, each entry also carries its `score`.

```bash
curl "https://api.nativeport.ai/v1/catalog?q=pdf%20ocr&limit=3"
```

### Price shapes

Every amount is in micro-credits: 1,000,000 µc = one credit = US\$1.

| `price.type`  | Fields                                               | Meaning                                                                                                                                                                            |
| ------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PER_CALL`    | `amountMicro`, `basis`                               | A fixed debit per successful call. `basis: "list"` is the provider's own price; `"approximation"` is a flat stand-in for a provider whose per-request cost the gateway cannot see. |
| `PER_UNIT`    | `unit`, `amountMicroPerUnit`, `typicalUnits`, `note` | Units × rate, units read from the exchange (`credit`, `token`, `page`, `byte`, `second`).                                                                                          |
| `PASSTHROUGH` | `source`, `note`                                     | The provider's own reported cost, debited without markup.                                                                                                                          |
| `PER_TOKEN`   | `modelsRoute`                                        | Model inference; per-model rates are on `GET /inference/v1/models`.                                                                                                                |
| `FREE`        | —                                                    | Never debited.                                                                                                                                                                     |

`expectedMicro` is the cost of one plain call when it can be known in advance, otherwise `null`.

## `GET /v1/catalog/{id}`

Public, cached like the list. Returns `{ entry, request, curl }`. The `request.url` is built against the origin you called, so it works against a local `wrangler dev` too. An unknown id answers `404` with `{ "error": "Unknown catalog id. List ids at GET /v1/catalog." }`.

```bash
curl https://api.nativeport.ai/v1/catalog/brave
```

## `GET /SKILL.md`

Public, `text/markdown`. Also served at `/skill.md`, and `https://nativeport.ai/SKILL.md` redirects here. The endpoint table inside is rendered from the catalog on every request.

## `GET /v1/account`

Requires your bearer and passes the same gate as every proxy, so an empty balance answers the usual `402`. Never debited, never cached.

```json
{ "balanceMicro": 2500000, "balanceUsd": 2.5, "status": "active" }
```

The catalog and skill are read-only and carry no secrets. They are rate-limited per client IP at the edge; a `429` there means slow down, not that the gateway is unavailable.