Agent recipes

Two flows an agent can follow literally. Each is shown as an ordered sequence of MCP tool calls, with the equivalent REST path beside it. Names and arguments are exactly those the API exposes — do not invent others.

Recipe A — draft → preflight → fix → schedule a cross-platform post

The goal: one Story published natively to a LinkedIn page and an X account, validated before it ships, scheduled for a future instant.

1. Find the channels

Call list_channels (REST: GET /channels) to get channel ids and connection health. Optionally call get_capabilities (GET /capabilities) to confirm each target can publish right now and to read its text limits.

2. Create the draft

Call create_post (REST: POST /posts) with the Story content and the target channels. One Story fans out into a rendition per channel automatically.

{
  "content": "We just closed our Series A — here's what's next.",
  "placements": [
    { "channel_id": "chn_linkedin_page", "format": "post" },
    { "channel_id": "chn_x_account", "format": "thread" }
  ],
  "idempotency_key": "series-a-announce-1"
}

The response returns the new post’s id. The draft appears in the dashboard drafts sidebar immediately.

3. Preflight

Call preflight_post (REST: POST /posts/preflight) to fit-check every placement with no persistence. The response gives a per-placement verdict — reachability, then scopes, then content — plus adapt warnings and lengths. If every placement is publishable, skip to step 5.

4. Fix what fails

When a placement is refused for a fixable reason, its verdict carries refusal.fixes with machine-readable repairs. Apply one with apply_fix (REST: POST /posts/{id}/apply-fix), targeting a single placement:

• trim_to_fold — trim over-length text to the fold.
• rebalance_thread — rebalance a thread with too many or too-long items.
• crop_to — crop an image to an accepted aspect ratio.

apply_fix returns the refreshed verdict and marks that rendition Edited. Re-run preflight_post until every placement is green.

5. Schedule

Call schedule_post (REST: POST /posts/{id}/schedule) with a future instant as ISO-8601 with an offset. The pipeline publishes automatically — no one needs to be online.

{ "at": "2026-07-21T09:00:00-07:00" }

For staggered per-placement times, use schedule_placements (REST: POST /posts/{id}/schedule-placements) instead, which takes a default fire time, per-placement overrides, and an optional cascade that spaces placements N minutes apart.

6. Confirm it shipped

After the scheduled instant, poll get_job_status (REST: GET /posts/{id}/status) for the per-target journey: overall status plus each target’s status, external id, published URL, and last error. To publish immediately instead of scheduling, call publish_post (REST: POST /posts/{id}/publish) with an idempotency_key so retries replay safely.

Recipe B — pull analytics for recent posts

The goal: gather engagement for the posts you published lately.

1. List recent published posts

Call list_posts (REST: GET /posts) filtered to status = published and, optionally, a scheduled-time range. This returns posts with their per-channel targets and ids.

2. Pull per-post metrics

For each post id, call get_post_metrics (REST: GET /posts/{id}/metrics). You get per-channel totals — impressions, reactions, comments, shares, clicks — plus the full snapshot time series for that post.

3. Or roll up by channel

To see a channel’s aggregate performance rather than one post’s, call get_channel_metrics (REST: GET /channels/{id}/metrics) for per-day engagement across that channel’s published posts, optionally restricted to a time range.

Notes for agents

• Timestamps always carry an offset. Send 2026-07-21T09:00:00-07:00 or a Z instant. Naive local times are rejected with a corrective error.
• Idempotency. Pass an idempotency_key (MCP) or Idempotency-Key header (REST) on create_post and publish_post so a retried call replays instead of duplicating.
• Durable, multi-step flows. For a packaged version of Recipe A, list_skills may expose a cross_platform_publish skill; read its JSON-Schema input, then run_skill and poll get_skill_run.