Making requests

All services live under https://api.hank.ai/v1/<service>/. Send JSON, send your key as a bearer token, read JSON back. There is no required SDK. Use any HTTP client. Here is the same authenticated request in three languages:

curl

curl https://api.hank.ai/v1/codesets/lookup \
     -H "Authorization: Bearer <YOUR_API_KEY>"

Python (requests)

import requests

resp = requests.get(
    "https://api.hank.ai/v1/codesets/lookup",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
resp.raise_for_status()
data = resp.json()

JavaScript (fetch)

const resp = await fetch("https://api.hank.ai/v1/codesets/lookup", {
  headers: { Authorization: "Bearer <YOUR_API_KEY>" },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

See Errors for status codes and Rate limits for throttling behavior.

Retries and the `Idempotency-Key` header

Send an Idempotency-Key header to make a retry safe to send. Use a different value for every distinct request. A UUID is a good value.

On a GET or HEAD request, the platform folds a retry that carries the same key and the same URL onto the first call's billing record. The retry costs no credits.

On a POST, PUT, PATCH or DELETE request, the platform does not fold. The gate that meters your call reads the request line only. It cannot read the request body, so it cannot tell two different bodies apart. It bills each attempt. Your key is still useful: the service behind the endpoint reads the same header and can refuse to do the work twice.

The MCP endpoint at https://api.hank.ai/mcp is different. The gateway reads the whole request, so it folds a retry of any method. Two calls fold only when the key, the tool and every argument match.

Do not reuse one key for different requests. The platform treats each distinct request as a new call and bills it.

Requests that cost no credits

These paths under /v1/<service>/ are free. They still need a valid API key, and they still count against your rate limits:

/openapi.json, /docs and /redoc
/health and /healthz
/favicon.ico, /robots.txt and /llms.txt
/static/...
the service root, for example /v1/codesets/
a GET of /mcp, which is the connect page in a browser and the event stream in an MCP client