# Domains API on API Mercado

> Let your customers use their own hostnames. You create a claim for a hostname with the DNS records your product needs; we check public DNS and tell you when your customer has set them up. Published by Capital Enesti and sold through API Mercado, an API marketplace: one gateway, one Key, pay per request from a prepaid balance.

This guide is for coding agents and developers. It explains how to get access, how to call this API through the gateway, and how to generate a typed client. Everything an agent needs is here or linked as markdown.

## Identifiers

- Human page: https://apimercado.com/discover/capitalenesti/domains-api
- Provider: Capital Enesti, gateway segment `@capitalenesti` (the public id `e72bpbz582mh` is also accepted, for URLs copied before slugs existed)
- API slug: `domains-api`
- Gateway base URL: `https://eu-north-1.apimercado.com/v1/@capitalenesti/domains-api/`
- Same API under the legacy id URL: `https://eu-north-1.apimercado.com/v1/e72bpbz582mh/domains-api/`
- OpenAPI document (no Key needed): https://eu-north-1.apimercado.com/v1/@capitalenesti/domains-api/openapi.json
- Current version: 1.1.1

## 1. Get a Key (one-time, needs a human with an account)

1. Sign in at https://apimercado.com and pick or create an organization.
2. Open https://apimercado.com/discover/capitalenesti/domains-api and press **Enable** (an org admin; it is instant, no approval).
3. Create a Key at https://apimercado.com/dashboard/keys. Keys start with `mk_live_`, are shown once, and spend the organization's balance, so keep them server-side, in an environment variable such as `APIMERCADO_API_KEY`.
4. Top up the balance at https://apimercado.com/dashboard/billing when the Free buffer is not enough.

## 2. Call it

Every request carries the Key in the `X-API-Key` header and goes to the gateway base URL plus the endpoint path from the OpenAPI document:

```sh
curl -i "https://eu-north-1.apimercado.com/v1/@capitalenesti/domains-api/v1/domains" \
  -H "X-API-Key: $APIMERCADO_API_KEY"
```

- The gateway strips the Key, authenticates to the provider itself and forwards the request. Response headers `X-Mercado-Cost-Micros`, `X-Mercado-Fee-Micros` and `X-Mercado-Balance-Micros` report what the call cost (integer micro-dollars, 1,000,000 = $1.00).
- Pricing: $0.00 up to $0.10 per request, plus a $0.00005 proxy fee per request. The provider may charge up to $0.10 on heavier requests.
- Errors from the gateway itself are JSON `{ "error": { "code", "message" } }` with codes such as `key_not_authorized`, `api_not_enabled`, `balance_exhausted`, `key_spend_cap_reached`, `org_suspended` and `rate_limited`. Upstream errors pass through unchanged.
- Balance check without spending: `GET https://eu-north-1.apimercado.com/v1/account/balance` with the same header.

## 3. TypeScript client (recommended)

`@apimercado/client` wraps openapi-fetch with the gateway URL, the Key header and the gateway error shape. Generate the types once from the OpenAPI document and commit the file:

```sh
npm install @apimercado/client
npx @apimercado/client generate @capitalenesti/domains-api -o domains-api.d.ts
```

```ts
import { createApimercadoClient, readCost } from "@apimercado/client";
import type { paths } from "./domains-api";

const domains_api = createApimercadoClient<paths>({
  provider: "@capitalenesti",
  api: "domains-api",
  apiKey: "mk_live_...", // read it from your environment, keep it server-side
});

const { data, error, response } = await domains_api.GET("/v1/domains");
if (error) throw new Error(error.error.code);
console.log(data, readCost(response).costMicros);
```

In CI, `npx @apimercado/client check domains-api.d.ts` exits 1 when the provider changed the spec; regenerate and let the compiler show what moved.

## 4. Any other language

Point an OpenAPI generator (openapi-generator, openapi-python-client, oapi-codegen, ...) at https://eu-north-1.apimercado.com/v1/@capitalenesti/domains-api/openapi.json. Set the server URL to `https://eu-north-1.apimercado.com/v1/@capitalenesti/domains-api/` and send `X-API-Key` on every request. The document already lists the gateway as its server.

## 5. Endpoints

- `GET /v1/domains`: List claims
- `POST /v1/domains`: Create a claim
- `GET /v1/domains/{id}`: Get a claim
- `DELETE /v1/domains/{id}`: Delete a claim
- `POST /v1/domains/{id}/verify`: Check now

Parameters, request bodies and response schemas are in the OpenAPI document above; the human reference is https://apimercado.com/discover/capitalenesti/domains-api?tab=reference.

## More

- Billing, Keys, spend caps and every error code: https://apimercado.com/llms/billing-and-keys.md
- Selling your own API here: https://apimercado.com/llms/publish-an-api.md
- Every API and document on the marketplace: https://apimercado.com/llms.txt
- Provider terms: https://capitalenesti.com/terms
- Provider privacy policy: https://capitalenesti.com/privacy