> Part of the API Mercado docs, in beta. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt # For agents This page is the reference an agent reads first. Every page on this site is also markdown: append `index.md` to its URL, or send `Accept: text/markdown`. The site map is [/llms.txt](/llms.txt), and [/llms-full.txt](/llms-full.txt) holds every page in one file. ## Find an API Search the catalog with a goal or keywords: ``` GET https://apimercado.com/discover/llms.txt?q= ``` The answer is markdown, best match first. Words are OR-ed and ranked, so describe the goal and try two or three variants. Every public API is also listed in the catalog's own [llms.txt](https://apimercado.com/llms.txt). ## Read an API Each API page has two machine-readable twins, both readable without a Key: | URL | What it is | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `https://apimercado.com/discover///llms.txt` | The setup guide: gateway base URL, pricing, how to get a Key, a typed client, every endpoint. | | `https://apimercado.com/discover///openapi.json` | The OpenAPI document as consumers see it, with the gateway as its server. | ## MCP server The catalog is also a remote MCP server, read-only and without sign-in, over Streamable HTTP: ``` https://apimercado.com/mcp ``` To add it to Claude Code: ```sh claude mcp add --transport http apimercado https://apimercado.com/mcp ``` In Claude.ai or Claude Desktop, add the URL as a custom connector under Settings > Connectors. | Tool | Returns | | ---------------------------------- | --------------------------------------------------------------------- | | `search_apis({ q, category? })` | Catalog search results, the same markdown as `/discover/llms.txt?q=`. | | `get_api_guide({ provider, api })` | An API's setup guide, the same markdown as its `llms.txt`. | | `get_openapi({ provider, api })` | An API's OpenAPI document as JSON, with the gateway as its server. | `provider` and `api` are the two slugs in a result's link, `/discover//`. An unknown API returns a tool error. Calling an API still needs a Key, as described below. Tool names are stable: renaming one is a breaking change in the [Changelog](/changelog/). ## Call an API Every call goes through the gateway with a Key in the `X-API-Key` header: ``` curl -H "X-API-Key: $APIMERCADO_API_KEY" "https://eu-north-1.apimercado.com/v1/@//" ``` - A Key starts with `mk_live_` and needs a human: an org admin enables the API on its page and creates the Key there, or on the Keys page. - Keys stay server-side, in an environment variable. A Key spends its organization's balance, so it never belongs in a browser, a repository or a prompt. A Spend cap on the Key bounds what it can spend in a Month. - Response headers report what each call cost (`X-Mercado-Cost-Micros`, in micro-dollars) and the balance left. See [Response headers](/billing-and-keys/#response-headers). - To bound what one call may cost, send `X-Mercado-Max-Cost-Micros` (an integer in micro-dollars, proxy fee included). When the called operation's price cap plus the proxy fee is above it, the gateway answers `402 max_cost_exceeded` before the provider is called and charges nothing; otherwise the provider receives the value and can scale the work to it. See [Max cost](/billing-and-keys/#max-cost). ### TypeScript client `@apimercado/client` generates types from an API's OpenAPI document and wraps the gateway URL, the Key header and the error shape: ```sh npm install @apimercado/client npx @apimercado/client generate @/ -o .d.ts ``` `npx @apimercado/client check .d.ts` exits 1 when the provider has changed the spec since the file was generated. For any other language, point an OpenAPI generator at the API's `openapi.json`. The same package sets a [Max cost](https://docs.apimercado.com/billing-and-keys/#max-cost) on every call (`maxCostMicros`), reads the billing headers (`readCost`), types the balance and request lookup (`createAccountClient`), and, for providers, the [Provider API](https://docs.apimercado.com/publish-an-api/#6-provider-api) (`createProviderClient`). ## Errors Errors the gateway generates share one envelope: ```json { "error": { "code": "balance_exhausted", "message": "The organization balance is exhausted.", "resets_at": "2026-11-01T00:00:00.000Z", "docs": "https://docs.apimercado.com/billing-and-keys/#balance_exhausted" } } ``` Branch on `code`, never on `message`. `docs` links to that code's section under [Error codes](/billing-and-keys/#error-codes), which says what caused it and what to do. Errors from the provider's own API pass through unchanged. ## Provider API A provider's servers and CI use the Provider API to work with their own APIs without a portal login. It lives at `https://admin-api.apimercado.com` under `/v1/provider/*`: | Operation | What it does | | ----------------------------------------------- | ---------------------------------------------- | | `GET /v1/provider/whoami` | Checks a key: its id, organization and scopes. | | `POST /v1/provider/apis/{apiId}/refresh` | Re-reads an API's spec from its URL now. | | `POST /v1/provider/requests/{requestId}/settle` | Sets the final price of a deferred request. | | `GET /v1/provider/requests/{requestId}` | Returns a deferred request's hold and status. | Authenticate with a provider API key, `Authorization: Bearer mpk_...`. An org admin creates it under Settings > Provider API; it is shown once. It cannot call APIs or sign in to the portal. Its errors are `{ "error": ": " }`. The details are in [Provider API](/publish-an-api/#6-provider-api). To get an API ready to publish, read [Publish an API](/publish-an-api/). ## Watch for breaking changes API Mercado is in beta: features and fees may change. Every Release is listed in the [Changelog](/changelog/), newest first, and changes that need action are under a "Breaking changes" heading in that Release's entry. To watch it, fetch `https://docs.apimercado.com/changelog/index.md` now and then and look for that heading in entries newer than the last one you read.