API guides
Playbook runs
Start a Playbook run from your own code over the REST API and poll it for the drafts.
A Playbook turns a source into a package of content: an article, social posts, and a video, all drafted together. Your team sets one up in the app and presses Run when there's something worth writing about.
The /v1/playbooks endpoints let something else press it. A CI job can draft a post when a release ships, or an internal tool can fill a publication on its own schedule.
A run creates drafts. Nothing is posted, emailed, or scheduled until someone approves it in the app.
See what you can run
Ask what's available rather than hard-coding settings. A Playbook describes its own, so a client built from this keeps working as Playbooks change.
curl https://api.paragraph.com/api/v1/playbooks \
-H "Authorization: Bearer your-api-key"{
"playbooks": [
{
"key": "changelog",
"name": "Changelog",
"summary": "Turn what your team ships into an article and posts.",
"fields": [
{ "key": "audience", "label": "Audience", "type": "string",
"required": true, "helperText": "Who the articles are written for." }
],
"deliverables": [
{ "key": "article", "label": "Paragraph article & newsletter", "required": true },
{ "key": "x_post", "label": "X posts", "required": false }
],
"installed": false,
"setup": null
}
]
}Set it up
curl -X PUT https://api.paragraph.com/api/v1/playbooks/changelog \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"repository": "acme/widget",
"values": { "audience": "Developers evaluating the SDK" },
"deliverables": ["article", "x_post", "linkedin_post"]
}'values is keyed by the field keys from the list above, and is checked the same way the app checks them, so a bad value comes back as a 400 explaining itself.
repository must be public. A private one needs a GitHub connection made in the app.
This replaces the setup rather than merging into it, and it changes what your team sees in the app. Send every field you want kept.
Start a run
A run takes several minutes, so this returns as soon as the work is queued.
curl -X POST https://api.paragraph.com/api/v1/playbooks/changelog/runs \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{ "idempotencyKey": "release-2.4.0" }'{ "runId": "0f2c...", "status": "queued" }idempotencyKey is yours to choose. Sending the same one again returns the run you already started rather than starting a second one, so a retried request is safe. Use something stable for the thing you're writing about, like a release tag.
instructions is optional and steers a single run, the same as the note you can add when pressing Run in the app.
Check on it
curl https://api.paragraph.com/api/v1/playbooks/changelog/runs/0f2c... \
-H "Authorization: Bearer your-api-key"{
"runId": "0f2c...",
"status": "succeeded",
"startedAt": "2026-10-09T09:00:00.000Z",
"finishedAt": "2026-10-09T09:04:12.000Z",
"deliverables": [
{ "export": "article", "item": null, "status": "ready" },
{ "export": "x_post", "item": "1", "status": "ready" }
]
}status is queued or running while it works, then succeeded, completed_with_warnings, failed, blocked, or canceled. Poll every 30 seconds or so; most runs finish in a few minutes.
deliverables fills in as pieces are written, so a run that is still running shows what it has so far.
List recent runs
curl "https://api.paragraph.com/api/v1/playbooks/changelog/runs?limit=5" \
-H "Authorization: Bearer your-api-key"Where the drafts go
Everything a run makes lands in the publication's library, under Content in the app. Read it with the content endpoints or review it in the app, where a person approves what goes out.