REST API

Describe events and payload fields

The event catalogue for subscriptions and list_events.

GET/v1/events/catalog

MCP tool describe_eventsscope companies:readNo record cost

Parameters

This operation takes no parameters.

What your agent reads

The tool description exactly as an MCP client receives it in tools/list — it doubles as the full behaviour of the endpoint.

The event catalogue for subscriptions and list_events: every event type you can see (with its attributes for `where`, a description and a sample), every payload path (`payload.fields`), the presets, the `where` operators, the envelope shape, and how deliveries are signed with a verification snippet for Node and Python. No record cost. Types of data layers not yet released for your organization are left out. Start here before create_subscription.

Request

curl -X GET "https://api.breaknorm.co/v1/events/catalog" \
  -H "Authorization: Bearer $BREAKNORM_API_KEY"

Response · 200

{
  "event_types": [
    {
      "type": "job.posted",
      "description": "A job posting first seen at a company, after enrichment (role, tech, intents) — up to 24 h after the ATS published it.",
      "scope": "global",
      "subscribable": true,
      "layer": "jobs",
      "attrs": {
        "posting_id": "string",
        "title": "string",
        "function": "string — Role Tree v2 function (roles layer)",
        "family": "string",
        "seniority": "string — training|unpaid|entry|mid|senior|manager|director|vp|partner|cxo|owner",
        "work_category": "string",
        "country": "string — ISO-2",
        "city": "string",
        "workplace": "string — onsite|hybrid|remote",
        "employment_type": "string",
        "tech": "string[] — catalogue slugs mentioned (any relation)",
        "tech_uses": "string[] — slugs the employer uses internally (incl. adopting/replacing)",
        "intents": "string[]",
        "posted_at": "date",
        "first_seen": "date",
        "repost_of": "string — posting id this one reposts; absent for a fresh vacancy",
        "source": "string — ATS",
        "url": "string",
        "lang": "string"
      },
      "sample": {
        "posting_id": "9876543",
        "title": "Senior Account Executive (DACH)",
        "function": "sales",
        "family": "account_management",
        "seniority": "senior",
        "country": "DE",
        "city": "Berlin",
        "workplace": "hybrid",
        "tech": [
          "hubspot",
          "gong"
        ],
        "tech_uses": [
          "hubspot"
        ],
        "intents": [],
        "posted_at": "2026-10-27",
        "first_seen": "2026-10-28T03:10:00Z",
        "source": "greenhouse",
        "url": "https://boards.greenhouse.io/example/jobs/9876543"
      }
    },
    {
      "type": "job.closed",
      "description": "A posting was taken down (absent from two consecutive complete polls).",
      "scope": "global",
      "subscribable": true,
      "layer": "jobs",
      "attrs": {
        "posting_id": "string",
        "title": "string",
        "function": "string",
        "seniority": "string",
        "country": "string",
        "closed_at": "date",
        "days_open": "number",
        "url": "string"
      },
      "sample": {
        "posting_id": "9876543",
        "title": "Senior Account Executive (DACH)",
        "function": "sales",
        "country": "DE",
        "closed_at": "2026-10-28",
        "days_open": 41
      }
    },
    {
      "type": "company.hiring.started",
      "description": "A company's hiring state changed — started",
      "scope": "global",
      "subscribable": true,
      "layer": "hiring",
      "attrs": {
        "subject": "string — the metric or flag (open_jobs, hiring_surge, hard_to_fill, leadership_hire, new_country)",
        "open_jobs": "number",
        "from": "string",
        "to": "string",
        "date": "date — the day the change was recorded"
      },
      "sample": {
        "subject": "open_jobs",
        "from": "0",
        "to": "3",
        "open_jobs": 3,
        "event": "started"
      }
    },
    "… 37 more"
  ],
  "fields": [
    {
      "path": "event.type",
      "type": "string",
      "description": "the event type",
      "sample": "job.posted"
    },
    {
      "path": "event.occurred_at",
      "type": "date",
      "description": "when the fact happened (ATS date, change day)",
      "sample": "2026-10-28T03:10:00Z"
    },
    {
      "path": "event.attrs",
      "type": "object",
      "description": "every attribute of the event (describe_events)",
      "sample": {
        "function": "sales"
      }
    },
    "… 96 more"
  ],
  "presets": {
    "minimal": [
      "event.type",
      "event.occurred_at",
      "company.domain",
      "… 2 more"
    ],
    "job_default": [
      "event.type",
      "event.occurred_at",
      "job.posting_id",
      "… 19 more"
    ],
    "company_default": [
      "event.type",
      "event.occurred_at",
      "event.attrs",
      "… 16 more"
    ],
    "person_default": [
      "event.type",
      "event.occurred_at",
      "person.name",
      "… 32 more"
    ],
    "full": [
      "event.type",
      "event.occurred_at",
      "event.attrs",
      "… 96 more"
    ]
  },
  "where": {
    "operators": {
      "eq": "equals (shorthand: `field: value`)",
      "in": "any of a list (shorthand: `field: [values]`)",
      "contains": "list contains the value / text contains the substring — a list means any of them",
      "not_contains": "none of the given substrings / values (true when the field is empty)",
      "gte": "≥ (numbers, dates)",
      "lte": "≤ (numbers, dates)",
      "exists": "true | false",
      "any": "OR of tiers: `any: [{…where…}, {…where…}]` — the persona waterfall; each tier is an AND of its clauses"
    },
    "example": {
      "function": [
        "sales"
      ],
      "seniority": {
        "in": [
          "senior",
          "manager",
          "director"
        ]
      },
      "tech": {
        "contains": "hubspot"
      },
      "repost_of": {
        "exists": false
      }
    }
  },
  "envelope": {
    "id": "evt_3f9a1c2b4d5e6f708192a3b4",
    "type": "job.posted",
    "occurred_at": "2026-10-28T04:12:00Z",
    "delivered_at": "2026-10-28T09:41:12Z",
    "attempt": 1,
    "subscription": {
      "id": "sub_0123456789abcdef0123",
      "name": "ACME – sales hires",
      "version": 3,
      "client": "acme"
    },
    "subject": {
      "domain": "example.com",
      "lists": [
        {
          "id": "lst_7a1b2c3d4e5f",
          "name": "ACME targets"
        }
      ]
    },
    "enrichment": {
      "status": "complete",
      "pending": [],
      "reason": null
    },
    "test": false,
    "data": {
      "event": {
        "type": "job.posted"
      },
      "job": {
        "title": "Senior Account Executive (DACH)"
      },
      "company": {
        "domain": "example.com",
        "name": "Example GmbH"
      }
    }
  },
  "signature": {
    "headers": [
      "content-type: application/json",
      "user-agent: breaknorm-webhooks/1",
      "x-breaknorm-event-id",
      "… 5 more"
    ],
    "scheme": "HMAC-SHA256 over `<timestamp>.<raw body>` with your endpoint secret; accept the request if ANY v1 value matches; reject timestamps older than your tolerance …",
    "verify": {
      "node": "import { createHmac, timingSafeEqual } from \"node:crypto\";\n// rawBody: the request body EXACTLY as received (a Buffer or string), not re-serialised JSON\nexpo…",
      "python": "import hmac, hashlib, time\n# raw_body: the request body bytes exactly as received\ndef verify(headers, raw_body: bytes, secret: str, tolerance_s: int = 300) -…"
    }
  },
  "limits": {
    "preview_window_days": 7,
    "list_events_max_limit": 1000
  },
  "price": {
    "company_row": "1 record per delivered payload that shows company fields (job.*, company.*, list.* events)",
    "person_row": "1 record per person row read outside a subscription (list_people_list_items with e-mail fields) and per person a find_people action adds to a payload",
    "monitor_people": "a person on a monitor costs once, 40 (commenter) or 80 (reactor), however you take them: delivered by a subscription (webhook and/or people list) or listed w…",
    "coming": "person.* events (champion tracking) are coming"
  }
}