Getting started with the API

Every endpoint lives under the /api/v1 prefix on the same host as this site, and every one of them speaks JSON.

https://your-host/api/v1

One organization at a time

The API is scoped to an organization rather than to an account. Almost every path carries the organization id:

GET /api/v1/tenants/{tenantId}/domains

You can find the id in the console URL when the organization is selected. An API token belongs to exactly one organization, and a request whose path names a different one is refused with 403 — the token cannot be pointed at a sibling organization by editing the URL.

A first request

curl https://your-host/api/v1/tenants/$TENANT_ID/domains \
  -H "Authorization: Bearer $COLDFEET_TOKEN"

The response is a JSON array of the domains Coldfeet filters mail for. If you get 401, the token is wrong or missing; 403 means the token is valid but not for this organization, or the endpoint does not accept tokens at all. See authentication and scopes for both cases.

Strict request bodies

Unrecognised properties are rejected rather than ignored. Sending a field the endpoint does not declare returns 400 with the offending property named, so a typo in a body key fails loudly instead of being silently dropped.

What to read next

• Authentication and scopes — creating a token and what it can reach.
• Errors, pagination and rate limits — the conventions every endpoint shares.
• Webhooks — being told about a verdict instead of polling for it.
• API reference — every endpoint, generated from the running server.