REST API overview

EchoSift exposes a REST API for direct HTTP access. All endpoints are read-only and return JSON.

Base URL

https://api.echosift.io

Authentication

All API endpoints require a Bearer token in the Authorization header:

Authorization: Bearer es_YOUR_KEY_HERE

API keys are created from Settings > Integrations in the EchoSift UI and require a Pro subscription. Keys follow the format es_<prefix>_<secret> and are shown only at creation time. Store them securely.

See Authentication for full details on key creation and revocation.

Scope

API keys carry read-only scope (ROLE_API_CLIENT). They can reach all data endpoints listed in Endpoints but cannot:

• Trigger opportunity brief generation (LLM quota-consuming).
• Access user profile, alerts, or billing endpoints.
• Access raw chunk records.

Rate limit

60 requests per minute per key. See Limits and fair use.

Response format

All responses are JSON. Paginated lists follow this envelope:

{
  "items": [...],
  "page": 0,
  "size": 20,
  "totalItems": 341,
  "totalPages": 18
}

Non-paginated lists return a plain JSON array.

Error responses

Status	Meaning
401	Missing or invalid API key
403	Key valid but Pro subscription required
404	Resource not found
400	Invalid query parameter
429	Rate limit exceeded
503	Semantic search unavailable (transient)

Error body:

{
  "code": "INVALID_MACRO_AREA",
  "message": "Unknown macroArea value: 'auth'. Valid values: AUTH_IDENTITY, ...",
  "path": "/api/pain-signals"
}

Quick smoke test

curl -s https://api.echosift.io/api/dashboard/overview \
  -H "Authorization: Bearer es_YOUR_KEY_HERE" | jq .totalSignals