Projects and entities
How Bellwork scopes seller context and K-12 records
Projects
A project is both a workspace and a seller profile. It stores the company, product, ICP prose, and territory used to frame briefs and agent research. Follows, tables, and briefs are project-scoped.
Use GET /projects to discover project IDs, POST /projects to create one,
and PATCH /projects/{projectId} to update the profile.
Districts and schools
Districts and schools are catalog entities with stable UUIDs. Search them with
GET /districts and GET /schools, then use their IDs in contacts, signals,
follows, and briefs.
The core record is visible on every plan. Where the plan gates a rich intelligence layer, an unfollowed entity returns a teaser with an exact count, and following the entity opens the layer.
Follows
A follow gives a project standing attention on a district or school and opens
its signals, news, leadership changes, and board meetings for that project.
Following does not start a brief; request one with POST /briefs (see
Briefs).
A plan can cap how many entities a project follows; at the cap, POST /follows
returns 403 FOLLOW_LIMIT with the slots in use. An unfollowed slot normally
remains occupied for 14 days; a follow undone within 24 hours releases
immediately.
Contacts and reveals
Names, roles, and affiliations are distinct from reachable contact information. Email, phone, and LinkedIn fields use the contact-reveal allowance. Once a contact is revealed to an organization, it remains revealed there.
Signals
GET /signals is the current cross-catalog signal feed. It supports time,
state, entity, and text filters plus pagination. Per-entity buying-signal routes
remain available for reading intelligence attached to a known district or
school, but they are not a substitute for the fresh feed.
Processing status
GET /districts/{districtId}/status and GET /schools/{schoolId}/status
report extraction progress for one entity. Treat status as pipeline state
only; it does not represent a purchasable unlock.