Bellwork
Start free
Briefs

Create or retry a brief

Idempotently request a deep-research brief for one (project, entity) pair. A ready brief is reused and a fresh in-flight build is not duplicated. Enterprise/internal organizations can request a brief without following the entity. Free organizations must follow it in the project first. Builds are asynchronous; poll the returned URL.

POST
/briefs

Idempotently request a deep-research brief for one (project, entity) pair. A ready brief is reused and a fresh in-flight build is not duplicated. Enterprise/internal organizations can request a brief without following the entity. Free organizations must follow it in the project first. Builds are asynchronous; poll the returned URL.

Authorization

AuthorizationBearer <token>

API key (sk_live_... prefix). Generate keys in the UI under Settings > API Keys, then send it as Authorization: Bearer sk_live_...

In: header

Request Body

application/json

project_id*string

UUID identifier

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
entity_type*string
Value in"district" | "school"
entity_id*string

UUID identifier

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/briefs" \  -H "Content-Type: application/json" \  -d '{    "project_id": "550e8400-e29b-41d4-a716-446655440000",    "entity_type": "district",    "entity_id": "550e8400-e29b-41d4-a716-446655440000"  }'
{
  "brief_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "building",
  "started": true,
  "poll": "string"
}
{
  "brief_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "building",
  "started": true,
  "poll": "string"
}
{
  "error": "string",
  "message": "string",
  "statusCode": -9007199254740991
}
{
  "error": "string",
  "message": "string",
  "statusCode": -9007199254740991
}
{
  "error": "string",
  "message": "string",
  "statusCode": -9007199254740991
}
{
  "error": "string",
  "message": "string",
  "statusCode": -9007199254740991
}
{
  "error": "string",
  "message": "string",
  "statusCode": -9007199254740991
}

Get a brief GET

The brief dossier for a (project, entity) pair — the read, the people who matter, what to do next, each claim sourced and dated. Following starts a build automatically; enterprise/internal clients can also request one directly. Returns `brief: null` when the pair has never had a build; a build stuck in `building` for over 60 minutes is reported as `failed`.

Promote a brief's person into a contact record POST

"Work this person". Stores a REFERENCE to the brief entry, never its prose: the approach renders from the brief and only where that brief is in scope, so one client's positioning cannot leak into another's view. A person with no corpus contact becomes an unlinked record you can merge later.