Skip to Content
API & MCPQuickstart

API & MCP

Quickstart

Your first search, exclusion list and export over REST in five minutes.

Create an API key in the dashboard (API keys), then:

export BN_KEY=bnk_live_…

1. Size a segment (free):

curl -s https://api.breaknorm.co/v1/companies/count \
  -H "Authorization: Bearer $BN_KEY" -H "content-type: application/json" \
  -d '{"filters": {"country": "DE"}, "group_by": ["company_type"]}'

2. Keep your customers out — once, and it applies to everything:

curl -s https://api.breaknorm.co/v1/lists \
  -H "Authorization: Bearer $BN_KEY" -H "content-type: application/json" \
  -d '{"name": "Customers", "kind": "exclusion", "auto_exclude": true,
       "domains": ["acme.de", "https://www.example.com", "[email protected]"]}'

Bigger lists: upload a CSV under Lists in the dashboard, or add up to 5,000 per call with POST /v1/lists/:list_id/items.

3. Search:

curl -s https://api.breaknorm.co/v1/companies/search \
  -H "Authorization: Bearer $BN_KEY" -H "content-type: application/json" \
  -d '{"match": [{"text": "industrial pump manufacturer", "in": ["summary", "offerings"]},
                 {"text": "chemical plants", "in": ["customers"]}],
       "filters": {"country": ["DE", "AT"]}, "k": 25}'

Each hit carries its score, what matched (matched), size and revenue bands with their source, and the company’s LinkedIn page with its source. applied_exclusions shows which lists kept companies out.

4. Export everything above a similarity:

curl -s https://api.breaknorm.co/v1/exports \
  -H "Authorization: Bearer $BN_KEY" -H "content-type: application/json" \
  -d '{"search": {"concept": "industrial pump manufacturer", "filters": {"country": "DE"}},
       "min_similarity": 0.6, "format": "csv", "idempotency_key": "pumps-de-1"}'
# → {"job_id": "job_…", "status": "queued", …}
 
curl -s "https://api.breaknorm.co/v1/jobs?job_id=job_…" -H "Authorization: Bearer $BN_KEY"
# → when "status": "done": result.download.url (signed, 24 h)

Retrying with the same idempotency_key returns the same job — never a second export or charge.

IntroductionAuthentication