REST API reference

The dashboard is built on this API, so anything you can do in the app you can script. The base URL is {API_URL}/api (http://localhost:4300/api on a default self-hosted install).

Authentication

Send an OpenReach API key as Authorization: Bearer oreach_…. Create keys under Settings; a key is shown once and acts as you, so treat it like a password. Keys can be revoked at any time and cannot create further keys. The dashboard itself uses a session cookie and may only make changes from its own origin.

Apps that sign in with OAuth, such as ChatGPT, get short-lived access tokens that work the same way. OpenReach is an OAuth 2.1 authorization server for its MCP endpoint, with discovery at /.well-known/oauth-protected-resource, dynamic client registration, PKCE (S256) and rotating refresh tokens.

Responses

Every response is JSON: { "ok": true, "data": … } on success, or { "ok": false, "error": { "code", "message", "details?" } } with a 4xx or 5xx status. Codes are listed in Errors and troubleshooting. IDs are UUIDs; a malformed one is a 404.

Lookups

POST /projects/:projectId/lookups/:name runs one paid lookup with its input as the JSON body. Inputs are validated before anything is spent; an omitted country or language defaults to the project’s. POST /lookups/:name runs the same lookups without a project, in the United States in English unless the input or ?country=&language= says otherwise.

# Price a lookup (free), then run it with a ceiling
curl -X POST "$API_URL/api/projects/$PROJECT/lookups/find_leads?dryRun=1" \
  -H "Authorization: Bearer $OPENREACH_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"plumber","location":"Austin, TX","pages":2}'

curl -X POST "$API_URL/api/projects/$PROJECT/lookups/find_leads?maxCostUsd=0.20" \
  -H "Authorization: Bearer $OPENREACH_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"plumber","location":"Austin, TX","pages":2}'

{
  "ok": true,
  "data": {
    "name": "find_leads",
    "estimate": { "min": 0.07, "max": 0.14 },
    "data": { "query": "plumber", "location": "Austin, TX", "pages": 2, "leads": [ ... ] },
    "costUsd": 0.14,
    "cached": false,
    "fetchedAt": "2026-10-25T09:30:00.000Z"
  }
}

cached: true results have costUsd: 0. A result where some searches failed carries a warnings or failed list and is not cached. Names: find_creators, analyse_creator, analyse_creators, similar_creators, find_leads, lead_emails, brand_mentions, find_conversations, find_subreddits. GET /lookups lists them with descriptions and cache times.

Account

Projects

GET/POST /projects, GET/PATCH/DELETE /projects/:projectId. Fields: name, domain, description, keywords (niche and problem words), competitors, locationCode, country, language, context (free-form notes for agents). Deleting a project deletes everything in it.

Creators

Leads and lead searches

Monitors and mentions

MCP

POST {API_URL}/mcp is the MCP server, stateless streamable HTTP, with the same authentication. Its tools call the routes above; see MCP tools.