Broadcasts API: the three prefixes at a glance
Generated from the broadcasts contract by tests/docs.test.ts (UPDATE_DOCS=1 rewrites it); do not edit by hand. The request and answer schemas, the Problem codes of each route and the MCP markers render on /api-reference from the platform OpenAPI document; this page is the map. A route that needs an Idempotency-Key header replays its first answer for the same key and body and refuses the same key with another body (409). Every refusal is a Problem Details body: a use case answers its code with reason codes and paths, never a submitted value; a body the request schema refuses answers 400 validation with the path of every issue (a refused map key is named in its path).
/v1/broadcasts
| Operation | Route | Scopes | Rate class | Idempotency-Key | Summary |
|---|---|---|---|---|---|
broadcasts.listBroadcasts | GET /v1/broadcasts | broadcasts:read | read | no | The tenant's broadcasts, newest first (filter by stream, state and creation window) |
broadcasts.createBroadcast | POST /v1/broadcasts | broadcasts:write | write | required | Create a draft broadcast on a broadcast-lane or test-lane stream of the tenant (422 validation for any other lane) |
broadcasts.getBroadcast | GET /v1/broadcasts/{broadcast_id} | broadcasts:read | read | no | One broadcast with its approval, workflow execution and timeline |
broadcasts.updateBroadcast | PATCH /v1/broadcasts/{broadcast_id} | broadcasts:write | write | no | Edit a draft or approved broadcast (an edit of an approved one returns it to draft, clears the approval and changes the content hash); scheduled and later are 409 conflict |
broadcasts.getChecklist | GET /v1/broadcasts/{broadcast_id}/checklist | broadcasts:read | read | no | The pre-send checklist (identity, stream, template, unsubscribe, consent, frequency, size, verification) with one sample render measured, never returned |
broadcasts.sendTest | POST /v1/broadcasts/{broadcast_id}/test | broadcasts:write | write | required | Send the rendered broadcast to at most 5 verified member addresses of the tenant (S21) through emails.send |
broadcasts.approveBroadcast | POST /v1/broadcasts/{broadcast_id}/approve | broadcasts:approve | write | no | Approve a draft (a human act): records the approver and locks the content hash; 409 conflict with the failing steps while the checklist has a blocking step |
broadcasts.scheduleBroadcast | POST /v1/broadcasts/{broadcast_id}/schedule | broadcasts:write | write | required | Schedule an approved broadcast now or up to 30 days ahead (the bulk start, S8): the content hash must match the approval, at most 3 scheduled or running broadcasts per tenant; agents need a broadcast.bulk_start grant |
broadcasts.cancelBroadcast | POST /v1/broadcasts/{broadcast_id}/cancel | broadcasts:write | write | no | Cancel a scheduled or running broadcast (remaining batches are skipped; messages emails already accepted are not recalled); completed is 409 conflict |
broadcasts.getReport | GET /v1/broadcasts/{broadcast_id}/report | broadcasts:read | read | no | Campaign counters from the batch responses and the consumed email events, with batch progress |
broadcasts.listRecipients | GET /v1/broadcasts/{broadcast_id}/recipients | broadcasts:read | read | no | Recipients of a broadcast as contact ids and hashes (never an address, D8); filter by state |
broadcasts.getStreamPolicy | GET /v1/broadcasts/streams/{stream_id}/policy | broadcasts:read | read | no | The campaign policy of a stream (defaults when none was saved) with the platform stream snapshot |
broadcasts.updateStreamPolicy | PATCH /v1/broadcasts/streams/{stream_id}/policy | broadcasts:write | write | no | Change the campaign policy of a stream of the tenant (stream.policy_changed.v1 only when a field changed) |
/v1/audiences
| Operation | Route | Scopes | Rate class | Idempotency-Key | Summary |
|---|---|---|---|---|---|
broadcasts.listAudiences | GET /v1/audiences | audiences:read | read | no | The tenant's audiences with member counts and consent coverage |
broadcasts.createAudience | POST /v1/audiences | audiences:write | write | required | Create a static audience through the platform write path; a duplicate name is 409 conflict |
broadcasts.getAudience | GET /v1/audiences/{audience_id} | audiences:read | read | no | One audience with member count, consent coverage and the last import |
broadcasts.listAudienceMembers | GET /v1/audiences/{audience_id}/members | audiences:read | read | no | Members as contact ids and hashes with consent and status (never an address, D8) |
broadcasts.removeAudienceMember | DELETE /v1/audiences/{audience_id}/members/{contact_id} | audiences:write | write | no | Remove a member through the platform write path; the consent history is kept |
broadcasts.createAudienceImport | POST /v1/audiences/{audience_id}/imports | audiences:write | import | required | Open a CSV import with its consent block (S20: a request without one is 422) and a presigned upload URL (15 minutes, at most 52428800 bytes) |
broadcasts.startAudienceImport | POST /v1/audiences/{audience_id}/imports/{import_id}/start | audiences:write | import | no | Start the import workflow once the file is uploaded (409 conflict while no object exists) |
broadcasts.getAudienceImport | GET /v1/audiences/{audience_id}/imports/{import_id} | audiences:read | read | no | Import state with row counts and the first 20 failures (row numbers and codes only) |
/v1/segments
| Operation | Route | Scopes | Rate class | Idempotency-Key | Summary |
|---|---|---|---|---|---|
broadcasts.listSegments | GET /v1/segments | audiences:read | read | no | The tenant's segments with their last counts |
broadcasts.createSegment | POST /v1/segments | audiences:write | write | required | Create a segment over an audience (conditions nest 3 deep, at most 20 conditions and 8 excluded segments; unknown fields or operators are 422) |
broadcasts.getSegment | GET /v1/segments/{segment_id} | audiences:read | read | no | One segment with its conditions and last count |
broadcasts.updateSegment | PATCH /v1/segments/{segment_id} | audiences:write | write | no | Rename a segment or change its conditions; 409 conflict while a scheduled or running broadcast uses it |
broadcasts.previewSegment | POST /v1/segments/{segment_id}/preview | audiences:read | preview | no | Count the segment up to 100000 (a lower bound above) and return 20 contact ids; cached 5 minutes |