Compass DocsBy Mesa
Open App

🏗️ Architecture & Infrastructure

This page is the wide-angle view: what the Compass API is, how a request travels through it, and the layers that sit between your key and the data. If you want the step-by-step version, see Request Lifecycle.

The shape

The API is a versioned REST plane in front of the same database that powers the app. Your systems talk to it; it talks to the data, applies the same people-first rules the app uses, and returns JSON.

Your system
    |
    v
Edge protection        rate limiting, bot detection, web application firewall
    |
    v
/api/v1 plane          versioned, stateless, JSON in and JSON out
    |
    v
Key authentication     bearer key -> hash lookup -> account
    |
    v
Scope and access       what this key is allowed to read
    |
    v
Usage metering         charges the call in credits (5 basic, 10 private reveal)
    |
    v
Data and serialization people-first records, internal fields stripped
    |
    v
JSON response

The layers

  • Edge protection. Before a request reaches the API, it passes through rate limiting, bot detection, and a web application firewall. This keeps the data plane fast and fair for real integrations. As a developer you feel this only if you go far past normal use, in which case you get a clear 429. See Access & Rate Limits.
  • Versioned /api/v1 plane. Every data endpoint lives under /api/v1. The version sits in the path, so a future /api/v2 can change shape without breaking your existing calls. Every response also carries a Compass-API-Version header (currently 1.1.1) for the build of the plane.
  • Key authentication. Each request carries a bearer key. The server hashes the key and looks up the matching account. Nothing about your session or cookies is involved, which makes the API safe to call from a server. See Authentication & API Keys.
  • Scope and access. A key carries scopes: read:metadata for data calls and read:contacts for revealing a contact's private channels. Keys are minted with both.
  • Credit metering. Every call is charged in credits: 5 for a data call, 10 for a private contact reveal, and 0 for /v1/me. Credits come from your plan; a call with too few credits returns 402 and is charged nothing. See Pricing & Quotas.
  • Data and serialization. Records come back in the same people-first shape as the app, with internal fields removed. You get the person, their team, their role, and how they connect, not Compass's private bookkeeping.

Design principles

  • People-first. The API exists to bring the right person, and the way you connect to them, into your own systems.
  • Stateless and versioned. Keys instead of sessions, a version in every path.
  • Honest metering. Billed in the same credits as the app, /v1/me free, and contact channels priced so the API never undercuts an in-app unlock.