Compass DocsBy Mesa
Open App

⚡ Your First Request

The identity endpoint is the simplest call in the API. It tells you which account a key belongs to, its plan, and its live credit balance. It is the right way to confirm a key works before you build on it, and it is free.

The request

curl https://api.compass.mesa.so/v1/me \
  -H "Authorization: Bearer ck_live_your_key_here"

The response

{
  "apiVersion": "1.4.0",
  "baseUrl": "https://api.compass.mesa.so",
  "docs": "https://compass.mesa.so/docs/api",
  "endpoints": [
    { "method": "GET", "path": "/v1/me", "summary": "Your identity, plan, credit balance, and this endpoint list. Always free.", "credits": 0 },
    { "method": "GET", "path": "/v1/people", "summary": "Search and filter people. Supports q, roles, channels, contactType, sort.", "credits": 5 }
    // ...every other endpoint, each with its own credit price
  ],
  "id": "clx0...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tier": "starter",
  "sampleMode": false,
  "organization": "Example Labs",
  "creditsBalance": 2850,
  "apiKey": {
    "label": "agent",
    "prefix": "ck_live_AbCdEf",
    "scopes": ["read:metadata", "read:contacts"],
    "environment": "live"
  },
  "pricing": {
    "currency": "credits",
    "basicCallCredits": 5,
    "privateCallCredits": 10,
    "note": "Data calls cost 5 credits. Revealing a contact's private channels costs 10 the first time, then 5."
  },
  "meta": { "creditsCharged": 0, "creditsBalance": 2850 }
}

What the fields mean

  • apiVersion is the API build you are talking to, also sent as the Compass-API-Version response header.
  • baseUrl and docs are where to send every other call and where to read more. Read them from here rather than hard-coding a host, and your integration follows us if either ever moves.
  • endpoints lists every endpoint with its method, path, purpose, and credit price. It is generated from the same price table that bills you, so what it quotes is what you are charged. This is the whole reference, in the response, for free.
  • id, name, email identify the account the key belongs to.
  • tier is the plan: free, starter, pro, team, or enterprise.
  • sampleMode is true when you are being served sample data rather than live. It depends on your balance, not your plan: it is true only on free with fewer credits than the call costs.
  • organization is your workspace name, or Compass if none is set.
  • creditsBalance is how many credits you have right now.
  • apiKey echoes the key you used: its label, display prefix, scopes, and environment.
  • pricing states the credit cost of a basic call and a private reveal.
  • meta reports what this call charged (0 for /v1/me) and your balance after it.

What comes next

/v1/me is free. Your next call, a data or search call, costs 5 credits (a private contact reveal costs 10). If creditsBalance is 0, fund the account first: see Pricing & Quotas. A call made with too few credits returns 402 Payment Required and charges nothing.

If it fails

A 401 means the key is missing, malformed, or revoked. Check that the header reads exactly Authorization: Bearer ck_live_… and that the key is still active in your API tab. See Errors & Status Codes.