🔀 Request Lifecycle

Here is what happens to a single request, from the moment you send it to the moment you get JSON back. This is the same path for every endpoint.

Step by step

You send a request. A standard HTTPS call to a path under https://api.compass.mesa.so/v1, with your key in the Authorization header.
Your key is resolved and your account is throttled. The key is hashed and looked up, then the call is counted against your account's per-minute allowance. Normal traffic flows straight through. Traffic far beyond normal use is refused with a 429.
The key is verified. The server reads the bearer token, hashes it, and looks up the matching account. If the key is missing, malformed, or revoked, the request stops here with a 401.
Scope is checked. The key's scopes decide whether it may read what the endpoint returns. A key without the right scope gets a clear error instead of data.
The call is charged in credits. A data call costs 5 credits, a private contact reveal 10, and /v1/me is free. If your balance is too low, the request stops here with a 402 and nothing is charged.
Data is fetched and shaped. The API reads from the same database as the app, then serializes the result into the people-first shape, removing internal fields. The API and the app share one field list per record type, so a field the website shows is a field the API returns.
You get JSON. A 200 with the data, or a clear status code and an { "error": "..." } body if something went wrong. Every response carries a Compass-API-Version header.

Send the key on every call. There is no session to keep alive. Each request stands on its own.
Handle 429 with backoff. If you are rate limited, wait and retry rather than hammering. See Access & Rate Limits.
Read the status code first. It tells you whether to read data or an error. See Errors & Status Codes.
Watch your balance. /v1/me reports your live credit balance, and a call with too few credits returns 402. See Pricing & Quotas.