Quickstart

1. Create an API key

In Bellwork, open Settings → API Keys, create a key, and store it in your server's secret manager.

export BELLWORK_API_KEY="sk_live_..."

2. Find a project

Projects are seller profiles and prospecting workspaces. Briefs and follows are scoped to a project because the same district should read differently for two different sellers.

curl -H "Authorization: Bearer $BELLWORK_API_KEY" \
  https://www.bellwork.ai/api/v1/projects

Create one when needed:

curl -X POST \
  -H "Authorization: Bearer $BELLWORK_API_KEY" \
  -H "Content-Type: application/json" \
  https://www.bellwork.ai/api/v1/projects \
  -d '{"name":"Northeast literacy prospects"}'

3. Search the catalog

curl -H "Authorization: Bearer $BELLWORK_API_KEY" \
  'https://www.bellwork.ai/api/v1/districts?state=MA&student_count_min=2000&limit=25'

Use limit and offset to page through larger result sets. Most list endpoints return a pagination object with has_more.

4. Read fresh signals

The signals feed is the current event stream. Narrow it by time, state, entity, or search terms and paginate instead of loading the entire feed at once.

curl -H "Authorization: Bearer $BELLWORK_API_KEY" \
  'https://www.bellwork.ai/api/v1/signals?state=MA&since=2026-07-01T00:00:00Z&limit=50&offset=0'

5. Request a brief

curl -X POST \
  -H "Authorization: Bearer $BELLWORK_API_KEY" \
  -H "Content-Type: application/json" \
  https://www.bellwork.ai/api/v1/briefs \
  -d '{
    "project_id":"PROJECT_UUID",
    "entity_type":"district",
    "entity_id":"DISTRICT_UUID"
  }'

The request is idempotent. It returns 202 when a build is running and 200 when a ready brief already exists. Poll the poll URL from the response until the brief is ready or failed.

Enterprise/internal organizations can request briefs without following. Free organizations must first POST /follows for the same project and entity.

Next steps

Browse the API reference
Learn how brief creation and polling work
Connect an AI assistant through MCP
Review rate limits