Let your AI agent build the newsletter.

For AI agents

This part is written for software. If you are an AI agent helping a person use lightbreak, everything you need is here, generated from the same catalog the API serves. The same reference as plain text: lightbreak.ai/agents.md.

AConnection

MCP endpoint

https://app.lightbreak.ai/api/mcp

Transport

Streamable HTTP, JSON responses. Protocol 2025-06-18 (also 2024-11-05, 2025-03-26)

Authentication

Authorization: Bearer lbk_... (workspace API key)

Plain HTTPS

POST https://app.lightbreak.ai/api/agent/<action> with the arguments as a JSON body

OpenAPI

https://app.lightbreak.ai/api/agent/openapi (send the key)

Scope

One workspace, newsletter-manager level, optionally limited to chosen publications

Errors

HTTP status with {"error": "plain-English sentence"}; over MCP the result has isError: true

Saving

save_issue_tree needs expected_updated_at; a newer save returns 409 conflict instead of overwriting

Email

Never sent. push_to_beehiiv and push_to_activecampaign create drafts only

Keys

Created by a workspace admin at Settings > AI agents & API; shown once; revocable

BRecommended workflow

1. list_publications, then list_issues for one publication.
2. Either generate_issue (lightbreak's own AI writes the whole issue; poll get_generation_status) or create_issue and fill it yourself.
3. get_selection_rules to read what belongs in this publication, get_template to inspect the saved layout, then get_issue to compare expected and present sections.
4. Hide a section that cannot be made good with set_section_visibility and a clear reason. This affects only this issue, is reversible, and prevents the section from appearing in previews or exports.
5. Edit: update_block_text for a single text block's words (update_event / update_job for events and jobs), update_issue_details for subject and preview text, or get_issue_tree + save_issue_tree for structural changes (always pass back the updatedAt you read).
6. review_issue, then poll get_review. The reviewer checks every visible link, image, fact (against each story's source) and sentence. Hidden sections are reported as skipped. Findings marked "wrong" include the source's own words. Fix what it finds and review again.
7. export_issue_html, or push_to_beehiiv / push_to_activecampaign when the issue is ready. mark_issue_done marks it finished in lightbreak.
8. Instead of polling, add_notification to be told when a draft is generated, a review finishes, or a draft reaches the ESP.

CActions (47)

DNotifications

Each message is a JSON POST with id, type, created_at, workspace_id, publication_id, issue_id, data and links. Headers: Lightbreak-Event, Lightbreak-Delivery, and Lightbreak-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">. Up to 3 attempts on timeout, 429 or 5xx. An address that fails 25 times in a row is switched off.

import { createHmac, timingSafeEqual } from "node:crypto";

// header = the Lightbreak-Signature request header, rawBody = the exact bytes received
export function isFromLightbreak(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = Buffer.from(createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return expected.length === given.length && timingSafeEqual(expected, given);
}

EExamples

POST https://app.lightbreak.ai/api/mcp
Authorization: Bearer lbk_YOUR_KEY
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"review_issue","arguments":{"issue_id":"ISSUE_ID"}}}

curl -X POST https://app.lightbreak.ai/api/agent/list_issues \
  -H "Authorization: Bearer lbk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

FRules for agents

1. Run review_issue before push_to_beehiiv or push_to_activecampaign, and fix every finding marked wrong.
2. Never state that a business is new, opening or long-established unless the source says so. Copy phone numbers, emails and addresses exactly.
3. Treat a 409 conflict as a person's edit: read the issue again, then reapply your change.
4. Tell the person which drafts you pushed. Sending always happens in their email platform.
5. Prefer notifications (add_notification) over polling for long jobs.

GMachine-readable files

/agents.md (this reference as markdown) · /llms.txt (site summary) · https://app.lightbreak.ai/api/agent/openapi (OpenAPI 3.1, needs a key)