Briefs

A brief is a deep-research dossier for one district, school, association or operator, 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.

Where the plan requires a follow before a brief, the entity must be actively followed in the same project first, or the API returns 403 BRIEF_REQUIRES_FOLLOW.

Association briefs use entity_type: "association" and the association UUID. They require a paid plan on both create and read; free accounts receive 403 BRIEF_REQUIRES_PAID_PLAN. Associations cannot be followed yet. Their briefs research the association's own workflows, contacts and board records, without assigning district data or member-school adoption to it.

Operator briefs use entity_type: "operator" and the operator UUID, on the same terms as association briefs: a paid plan on create and read, and no follow. They research the organization that runs the childcare centers or Head Start programs: where it operates, what its IRS Form 990s say (revenue, expenses, employees and the contractors each return names), its own contacts and its public sources.

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

Following does not start a brief. POST /follows gives the project standing attention on the entity and opens its layers; request the brief itself with POST /briefs, which is also how a failed build is retried.