Getting started

1. Get a key

Sign in at https://dashboard.castomapi.com/ with a castomo account — the one you use for dash-b, castomo or any product of the family. The dashboard mints API keys; the raw key is shown once. Keys can be revoked from the same screen.

2. Make a call

Every metered endpoint takes the key in the x-api-key header. Bodies are JSON. This is the whole ceremony:

curl -X POST https://app.castomapi.com/v1/verify/iban \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"iban": "PL61109010140000071219812874"}'

That header is the only scheme a metered endpoint accepts; an Authorization: Bearer token will not authenticate one. Bearer belongs to the account side instead: the dashboard and account APIs take a JWT session, and castomapi-auth issues those through a standard OAuth2 handshake — authorization code, client credentials and refresh grants, with /oauth/authorize, /oauth/token and /oauth/userinfo. Connecting a customer's Shopify or Google account is a third thing again, and step 7 covers it.

3. Read the envelope

Every success answers status: "success", the payload, and tokensDeducted — the cost of the call you just made. Every error answers status: "error", a machine code, a message written for a person, and the HTTP status. Validation errors add a details array naming the field.

{ "status": "success", "valid": true, "country": "PL", "tokensDeducted": 1 }

{ "status": "error", "code": "VALIDATION", "message": "body/iban must be a string", "statusCode": 400,
  "details": [{ "field": "iban", "reason": "must be string" }] }

4. Understand the wallet

• Each endpoint's cost is in its description and on its page here. Most cost one token.
• The debit happens after the response, and only for a status under 400. Failures are free.
• Every account is topped up to 1000 tokens the next time it is used once a month has passed — not on a fixed date. Paid balances never expire.
• 69 routes need no key and no wallet at all: called without a key they answer 200, deduct nothing, and are limited to 10 requests a minute per IP.
• A wallet may run a small overdraft rather than refuse a request mid-flight; it nets out against the next top-up.
• GET /wallet/balance and GET /wallet/ledger are free and show every movement.

5. Handle the errors

6. Know the limits

Limits are per account across every endpoint. Unauthenticated requests are limited per IP at 10 a minute.

7. Connect a platform

Integrations connect the end user's own account. From a dashboard session call the platform's auth/url, send the user there, and after consent every call to that group works with your key. Several accounts on one platform are told apart with accountId. Details on the integrations page.

8. Take it to n8n, Make, Zapier or an agent

POST /v1/ecosystem/export generates native node packages for n8n and Make from any set of endpoints. The Zapier group has hooks, batches and async jobs. The MCP server exposes the catalogue to any Model Context Protocol client as tools.

9. Read the machine-readable spec

The OpenAPI 3 document behind the live docs and behind this site: https://app.castomapi.com/docs/json. Generate a client from it, diff it between releases, feed it to an agent. This site's llms.txt and llms-full.txt are the same catalogue condensed for language models.