API Reference

Use Beacon from your own app, scripts, or internal tooling.

Beacon's current authenticated HTTP API is centered on creating research briefs and reading run state.

Search docs, support, and public pages

Endpoints

Current practical endpoints

POST /api/briefs

Create a private research run for the signed-in user account.

GET /api/briefs

List the current account's research runs with synced workflow status.

GET /api/briefs/[id]

Read one run if and only if it belongs to the current account.

GET /api/logs

Read account-scoped workflow and memory log entries.

Create A Brief

POST /api/briefs

Request body:
{
  "topic": "string, required",
  "objective": "string, optional",
  "focus": "string, optional",
  "source": "dashboard | slack | github | discord | mcp",
  "depth": "quick | deep",
  "timeframe": "7d | 30d | 90d | all",
  "reportStyle": "executive | bullet | memo | framework",
  "recurring": false,
  "frameworkId": "optional framework id",
  "userKeys": {
    "groqApiKey": "optional",
    "serpApiKey": "optional"
  }
}

Response shape:
{
  "userId": "clerk user id",
  "runId": "workflow run id",
  "topic": "normalized topic",
  "status": "running",
  "source": "dashboard",
  "recurring": false,
  "runCount": 1,
  "hasMemory": false,
  "memoryFacts": 0,
  "createdAt": "ISO timestamp",
  "currentStep": "loadMemory",
  "frameworkId": "market-map"
}

Constraints

Authentication and limits

Auth required

The private briefs API is protected by Clerk auth and returns 401 when no user session exists.

Rate limited

Research creation is capped per IP because each run burns SerpAPI and model budget.