Briefs

A brief is a deep-research dossier for one district or school, framed by the seller profile stored in a project. It includes a narrative read, people who matter, concrete next steps, verified facts, confidence, caveats, and sources.

Create or retry

POST /api/v1/briefs
Content-Type: application/json

{
  "project_id": "PROJECT_UUID",
  "entity_type": "district",
  "entity_id": "DISTRICT_UUID"
}

The operation is idempotent:

• A ready brief returns 200 with started: false.
• A fresh build returns 202 with started: false.
• A missing, failed, or stale build starts a durable research run and returns 202 with started: true.

Enterprise/internal organizations can create a brief without a follow. A free organization must actively follow the entity in the same project first, or the API returns 403 BRIEF_REQUIRES_FOLLOW.

Poll and retrieve

The create response includes a relative poll URL. A brief build normally takes several minutes.

GET /api/v1/briefs?project_id=PROJECT_UUID&entity_type=district&entity_id=DISTRICT_UUID

The response contains brief: null before any request. While building, the brief includes a bounded chronological progress trail. Once complete, status is ready; a build that fails or remains stuck for more than 60 minutes is reported as failed and can be retried with POST /briefs.

The API does not send a completion webhook yet. Poll every 30–60 seconds rather than continuously.

Following

POST /follows still starts a brief automatically. Use an explicit brief request when an enterprise integration wants a dossier without adding standing follow state, or when it needs to retry a failed build.