Pitches

list_pitchesCopy Anchor Link

List pitches for the org (newest-first by effective rank, paginated, optionally filtered by title). Returns { items, nextCursor }. Pass cursor from a prior nextCursor to fetch the next page. Each pitch carries url (a link to it in the web app), newsdeskName, and orgName alongside the existing raw newsdeskId.

read-only · idempotent · closed-world

• limit integer — Items per page (1–100, default 25)
• cursor string — Opaque cursor from a prior nextCursor
• newsdeskId string — Filter to pitches for this newsdesk
• title string — Filter to pitches whose title contains this text (case-insensitive)
• topic string — Filter to pitches whose event cluster has this topic
• location string — Filter to pitches whose event cluster has this location
• status string — one of draft, new, approved, dismissed — Filter by editorial review status (e.g. "new" for pitches still awaiting review)

get_pitchCopy Anchor Link

Get a pitch by ID. A pitch a person created (preview_pitch) also carries seeds: the material it was built from, including the journalist's own text, PDF and image seeds, which are internal to the org. Carries url (a link to it in the web app), newsdeskName, and orgName alongside the existing raw newsdeskId.

read-only · idempotent · closed-world

• id string (required) — Pitch identifier

approve_pitchCopy Anchor Link

Approve a pitch, minting a story from it. Only a pitch with status "new" or "draft" can be approved. A draft can be changed only by the user who created it: anyone else, a service key included, gets a 403 (Only the person who created this draft can change it). A repeat call on an already-approved or already-dismissed pitch returns a 409 conflict error and does not silently re-approve it. The response carries storyId and storyUrl (a link to the newly minted story in the web app) alongside url (the pitch's own link): show storyUrl to the user.

destructive · idempotent · closed-world

• id string (required) — Pitch identifier

dismiss_pitchCopy Anchor Link

Dismiss a pitch, ending its review with no story minted. Only a pitch with status "new" or "draft" can be dismissed. A draft can be changed only by the user who created it: anyone else, a service key included, gets a 403 (Only the person who created this draft can change it). A repeat call on an already-dismissed or already-approved pitch returns a 409 conflict error and does not silently re-apply.

destructive · idempotent · closed-world

• id string (required) — Pitch identifier

preview_pitchCopy Anchor Link

Start building a manual pitch from seeds: text the journalist wrote, https URLs (web articles or X posts), library articles, and PDFs or images that were already uploaded (pdf and image seeds take an existing asset id, not file content). The brief and score are generated out of band. Returns the pitch request at once (status "pending") without a draft; poll get_pitch_request with its id until status is "done", which carries the draft pitch's pitchId, then call submit_pitch to put the draft in the review queue (or approve_pitch to approve it directly). 1 to 10 seeds, at most 5 URLs and 5 files. xCredentialId is required when any URL is an X post. replacesPitchId names a draft this preview replaces once it lands. Not idempotent: a repeat call queues a second request and spends a second generation. Refused when the org's spending cap has stopped paid work. Needs a user credential, so an interactive MCP connection: a static API key authenticates as a service and there is no user to record as the pitch's creator.

additive · closed-world

• newsdeskId string (required) — The desk the pitch is for, of the caller's org
• eventDate string — ISO 8601 date (YYYY-MM-DD) of the event, overriding the one the brief would carry
• angle string — The framing the brief should take, 1 to 1000 characters. It steers the title, summary and why it matters; every claim still comes from the seeds. Omit it rather than send it blank
• replacesPitchId string — A draft the caller created this preview replaces once it lands
• xCredentialId string — An org credential tagged with the X preset; required when any URL is an X post
• seeds array (required) — The pitch's evidence, in order: 1 to 10 seeds, at most 5 URLs and at most 5 files

get_pitch_requestCopy Anchor Link

Poll a pitch request started by preview_pitch. Returns its status ("pending", "claimed", "done", "failed" or "dismissed"), its normalized seeds, warnings, and, when failed, the failure reason with per-seed detail. Once status is "done", pitchId is the draft pitch and url links to it: use pitchId from then on (get_pitch, submit_pitch, approve_pitch). Generation takes tens of seconds. A request is its creator's alone: another user's request is reported as not found. Needs a user credential, so an interactive MCP connection: a static API key authenticates as a service and has no requests of its own.

read-only · idempotent · closed-world

• id string (required) — Manual pitch request identifier

submit_pitchCopy Anchor Link

Submit a draft pitch (the result of preview_pitch, found through get_pitch_request) for review: its status moves from "draft" to "new" and it joins the review queue. Only a draft can be submitted; a repeat call on a pitch that is already submitted returns a 409 conflict error and does not silently re-apply. Only the user who created the draft can submit it: anyone else, a service key included, gets a 403 (Only the person who created this draft can change it).

additive · idempotent · closed-world

• id string (required) — Pitch identifier