REST API
All endpoints
Every REST endpoint of api.breaknorm.co/v1 — the same operations as the MCP tools, generated from the server.
Base URL https://api.breaknorm.co. Authenticate with Authorization: Bearer <API key or OAuth token>. Request bodies are JSON; GET parameters go in the query string; :name segments are path parameters. Unknown fields are rejected — a typo is an error, not silently ignored. Errors share one format.
Discover
| Endpoint | What it does | |
|---|---|---|
| List filters | GET /v1/filters | Every filterable facet with its type and coverage %, plus the search axes. |
| List filter values | POST /v1/filters/values | Existing values of a keyword facet with counts (and its coverage), optionally under filters. |
Companies
| Endpoint | What it does | |
|---|---|---|
| Search companies | POST /v1/companies/search | Records: one per company shown (each hit, every time it is shown); count_companies and list_filters are free. |
| Run several searches and merge them | POST /v1/companies/search-many | Records: one per company shown (each hit, every time it is shown); count_companies and list_filters are free. |
| Count companies | POST /v1/companies/count | How many companies match a set of filters and literal guards — and, with group_by (≤3 keyword facets), how they split. |
| Find similar companies (lookalikes) | POST /v1/companies/similar | Records: one per company shown (each hit, every time it is shown); count_companies and list_filters are free. |
| Get companies by domain | POST /v1/companies/get | Records: one per company returned. |
| Segment companies | POST /v1/companies/segment | Split a set of companies into sub-segments you can write ONE message to. |
Jobs & hiring signals
| Endpoint | What it does | |
|---|---|---|
| Search job postings | POST /v1/jobs/search | Records: one per posting shown; count_jobs is free. |
| Read job postings (full text) | POST /v1/jobs/postings | Records: one per posting returned. |
| Count job postings | POST /v1/jobs/count | Free. |
| Company activity (jobs intelligence) | POST /v1/companies/activity | Records: one per company found. |
Crawled pages
| Endpoint | What it does | |
|---|---|---|
| List a company’s crawled pages | GET /v1/companies/pages | The pages we crawled from a company’s website: page_id, url, kind, when it was fetched and its length. |
| Read a crawled page | GET /v1/pages | The markdown of one crawled page of a company’s website — by page_id, or by domain + kind for the newest page of that kind. |
| Check known companies’ pages for words | POST /v1/pages/check | For up to 50 companies you already have, which of up to 10 terms appear on their crawled pages. |
People
| Endpoint | What it does | |
|---|---|---|
| Search people (contacts at companies) | POST /v1/people/search | Find people — decision makers, a team, a persona — with their contacts, at the companies you choose. |
| Count people | POST /v1/people/count | How many people match — and at how many companies — before you pull them. |
| Get people by id | POST /v1/people/get | Full records for up to 100 people by person_id. |
| Get (and re-check) a person’s contacts | POST /v1/people/contacts | The contacts of up to 25 people, with every address checked again when its verdict is older than max_age_days or never checked. |
| List people filter values | POST /v1/people/values | The values of a person field with how many people carry each. |
| Find a company’s decision makers live | POST /v1/people/live | For companies where search_people / get_contacts return nobody. |
| Get live people results | POST /v1/people/live/results | Current result of find_people_live lookups (lookup_ids from its answer). |
| Find decision makers live for many companies | POST /v1/people/live/jobs | find_people_live for a list of companies (items=[{domain, company_name?, ref?}], up to your plan’s e-mail batch size). |
Lists & exclusions
| Endpoint | What it does | |
|---|---|---|
| Create a company list | POST /v1/lists | Create a list of companies (by domain). |
| Add companies to a list | POST /v1/lists/:list_id/items | Add companies to one of your lists. |
| Remove companies from a list | DELETE /v1/lists/:list_id/items | Remove domains from one of your lists. |
| Get your lists | GET /v1/lists | Your organization’s company lists (id, name, kind, client, auto_exclude, size, how many the index knows). |
| Delete a list | DELETE /v1/lists/:list_id | Delete one of your lists (REST and dashboard only). |
Exports & jobs
| Endpoint | What it does | |
|---|---|---|
| Export a full company list | POST /v1/exports | Export EVERY company matching a search or a lookalike — not just the top 100. |
| Get a job’s status and result | GET /v1/jobs | Status and result of an export, e-mail, list-import or live-people job (job_id), with a fresh 24 h download link once done. |
| Cancel a job | DELETE /v1/jobs/:job_id | Cancel a queued or running job. |
| Endpoint | What it does | |
|---|---|---|
| Find a person’s e-mail address | POST /v1/email/find | Find the work e-mail address of a person from their name and company domain, verified against the mail server. |
| Verify an e-mail address | POST /v1/email/verify | Check whether an e-mail address is deliverable, without sending mail. |
| Get a pending e-mail result | GET /v1/email/tasks/:task_id | Result of a find_email / verify_email that answered {status:‘pending’}. |
| Verify or find e-mails in bulk | POST /v1/email/jobs | Verify a list of e-mail addresses or find addresses for people. |
Account
| Endpoint | What it does | |
|---|---|---|
| Get plan and usage | GET /v1/usage | Your organization’s plan, access state and allowance in records, with two rolling windows — used, left and limit for each. |
Webhooks & events
| Endpoint | What it does | |
|---|---|---|
| Describe events and payload fields | GET /v1/events/catalog | The event catalogue for subscriptions and list_events. |
| List events (polling feed) | GET /v1/events | Events in the order we recorded them, after a cursor. |
| Create a webhook endpoint | POST /v1/webhooks/endpoints | Register a receiver URL for event subscriptions. |
| List webhook endpoints | GET /v1/webhooks/endpoints | Your organization’s webhook endpoints with status (pending | active | paused | disabled) and delivery health. |
| Update a webhook endpoint | POST /v1/webhooks/endpoints/:endpoint_id | Change an endpoint. |
| Delete a webhook endpoint | DELETE /v1/webhooks/endpoints/:endpoint_id | Delete an endpoint (REST and dashboard only; soft-deleted for audit). |
| Create a subscription (webhook and/or people list) | POST /v1/subscriptions | Subscribe to events and deliver the matches to a webhook endpoint and/or a people list. |
| Preview a subscription | POST /v1/subscriptions/preview | Dry run of a subscription body over the recorded events of the last window_days. |
| List subscriptions | GET /v1/subscriptions | Your organization’s event subscriptions (full stored body, status active | paused | invalid with invalid_reason, version, matched_total). |
| Update a subscription | POST /v1/subscriptions/:subscription_id | Change any part of a subscription (every key optional; a given key replaces the stored one whole) and/or set status active | paused. |
| Delete a subscription | DELETE /v1/subscriptions/:subscription_id | Delete a subscription (REST and dashboard only; soft-deleted for audit). |
| Send a test event | POST /v1/subscriptions/:subscription_id/test | Queue ONE test delivery to the subscription’s endpoint. |
| List a subscription’s matches | GET /v1/subscriptions/:subscription_id/matches | What a subscription did, newest first: each matched event with its state, suppressed_reason, enrichment status, and every delivery attempt. |
| Redeliver | POST /v1/deliveries/redeliver | Queue new delivery attempts with the ORIGINAL stored bytes (nothing is re-rendered or re-charged). |
LinkedIn monitors (post engagers, champion tracking)
| Endpoint | What it does | |
|---|---|---|
| Describe monitors | GET /v1/monitors/catalog | What a LinkedIn monitor is and how to use one. |
| Estimate a monitor | POST /v1/monitors/estimate | Before creating: how many people a profile’s posts draw per month or one post’s counts, and the records that would cost if every one of them were delivered — comments only vs… |
| Create a monitor | POST /v1/monitors | Watch a LinkedIn profile’s posts or one post and collect the people who engaged; or watch a people list for job changes. |
| Collect a post’s engagers | POST /v1/monitors/collect | Shorthand for create_monitor: collect the commenters of ONE LinkedIn post now. |
| List monitors | GET /v1/monitors | Your organization’s monitors with status, target, settings and counters (posts, people collected, resolved, last poll). |
| Update a monitor | POST /v1/monitors/:monitor_id | Pause / resume a monitor, or change its name, collect settings, exclude or limits. |
| Delete a monitor | DELETE /v1/monitors/:monitor_id | Delete a monitor (REST and dashboard only; soft-deleted for audit). |
| List a monitor’s people | GET /v1/monitors/:monitor_id/people | The people a monitor collected, newest first. |
People lists
| Endpoint | What it does | |
|---|---|---|
| Create a people list | POST /v1/people-lists | Create a list of PEOPLE. |
| List your people lists | GET /v1/people-lists | Your organization’s people lists (id, name, client, size, version). |
| Add people to a people list | POST /v1/people-lists/:list_id/items | Add people by LinkedIn profile URL (up to 5000 per call), with optional name, title, company and e-mail. |
| Remove people from a people list | POST /v1/people-lists/:list_id/remove | Remove people (by LinkedIn profile URL) from one of your people lists. |
| Read a people list | GET /v1/people-lists/:list_id/items | The people on one of your people lists, newest first, with the fields you ask for. |
| Delete a people list | DELETE /v1/people-lists/:list_id | Delete one of your people lists (REST and dashboard only; soft-deleted for audit). |
Files
GET /v1/files/:job downloads a finished job’s file. The link comes signed from get_job and needs no bearer token.