# PostRelay

> Agent-first delivery of approved social creative. Humans handle setup and exceptions.

PostRelay delivers approved copy and creative to connected social accounts. Call whoami_and_health then get_capabilities first. No visual changes without explicit opt-in; preserve originals, pad by default, never crop, stretch, regenerate or silently change copy. Always preview and get user approval of the exact revision and every change before publishing unless autopublish is on. Humans connect accounts and resolve exceptions; agents do the work. Import untouched files with import_chat_files (ChatGPT MCP), import_gpt_files (Custom GPT action), import_media (HTTPS), or create_upload then PUT bytes (local agents). Supply idempotency_key on retryable writes and reuse it only for identical inputs. Inspect plan_variants for sourced limits and needs_trim; render_variants can plan with account_ids. Never trim automatically. Poll get_render_status no sooner than retry_after_s; ready requires measured verification. Eager frames have output-relative t_s and links; only Claude may receive bounded embedded images. Caption frames are unavailable until live still-caption verification. transcribe_media requires workspace consent and Cloudinary's paid Google transcription add-on. Return SRT to the user for review. Burn only with subtitles.burn_in=true; sidecars do not change pixels. Review caption text, fps, audio, padding and tone-map changes in preview_post. Create/update draft, validate_post (includes preview on success), approve, then publish_post or schedule_post with dry_run:true before delivery. Repeat without dry_run with the same key. Use get_post_status for per-account receipts; submitted/scheduled is not published. Read postrelay://guide/workflow, video, copy and errors and postrelay://platforms/{platform}. get_trend_context returns only source-linked, timestamped, scoped evidence, including the TikTok trending music chart when configured; it is not a performance claim or permission to change audio. Ad-derived guidance is explicitly labelled and is not organic performance evidence. Structured errors have stable code and next_actions. Reconnect via /connect when unauthenticated, not an authenticated tool. Credentials belong in secure setup, never chat.

Humans without an assistant can use Studio at /app/studio; posts made there appear in list_posts like any other.

## Connect
- [Connection instructions](https://post-relay.io/connect): MCP, OAuth and client setup.
- [MCP server](https://post-relay.io/api/public/mcp): Scoped authenticated tools.
- [OpenAPI](https://post-relay.io/api/public/openapi.json): Served OpenAPI 3.1, including GPT file import.

## Tools
- [transcribe_media](https://post-relay.io/api/public/v1/tools/transcribe_media): For a consented video, requests paid transcription. Returns caption job IDs or unavailable; next get_media. Never burns captions.
- [whoami_and_health](https://post-relay.io/api/public/v1/tools/whoami_and_health): For connection checks. Returns workspace, scopes and blockers; next get_capabilities.
- [get_capabilities](https://post-relay.io/api/public/v1/tools/get_capabilities): For planning. Returns sourced limits, client support, consent and processors; next list_accounts.
- [list_accounts](https://post-relay.io/api/public/v1/tools/list_accounts): For choosing destinations. Returns connected account IDs; next plan_variants or create_draft.
- [create_upload](https://post-relay.io/api/public/v1/tools/create_upload): For local files. Returns signed upload URL and PUT headers; next PUT bytes then get_media.
- [import_media](https://post-relay.io/api/public/v1/tools/import_media): For accessible HTTPS media. Returns untouched stored asset; next get_media. Private hosts are refused.
- [import_chat_files](https://post-relay.io/api/public/v1/tools/import_chat_files): For ChatGPT attached files. Returns immediate safe imports from MCP file params; next get_media.
- [get_media](https://post-relay.io/api/public/v1/tools/get_media): For uploaded assets or caption jobs. Returns measurements, variants and captions; next plan_variants.
- [plan_variants](https://post-relay.io/api/public/v1/tools/plan_variants): For target accounts. Returns deterministic padded plans and trim requirements without frames; next render_variants.
- [render_variants](https://post-relay.io/api/public/v1/tools/render_variants): For approved media adaptations. Returns eager variant IDs and verification status; next get_render_status. Deprecated subtitles_srt and cover_at_s aliases remain accepted.
- [get_render_status](https://post-relay.io/api/public/v1/tools/get_render_status): For pending variants. Returns measured status, eager frames and retry_after_s; next preview_post when ready.
- [create_draft](https://post-relay.io/api/public/v1/tools/create_draft): For final per-account copy and media. Returns draft ID, revision and hash; next validate_post.
- [update_draft](https://post-relay.io/api/public/v1/tools/update_draft): For revised copy or media. Returns a new revision and hash with approval invalidated; next validate_post.
- [validate_post](https://post-relay.io/api/public/v1/tools/validate_post): For current drafts. Returns sourced issues or inline preview; next preview_post or publish_post dry_run.
- [preview_post](https://post-relay.io/api/public/v1/tools/preview_post): For reviewing a revision. Returns exact copy, measured media, eager frames and changes hash; next publish_post or schedule_post.
- [publish_post](https://post-relay.io/api/public/v1/tools/publish_post): For approved validated revisions. Returns per-account submission status, or exact payload checks with dry_run; next get_post_status.
- [schedule_post](https://post-relay.io/api/public/v1/tools/schedule_post): For approved validated future deliveries. Returns scheduler status or dry-run payload checks; next get_post_status.
- [get_post_status](https://post-relay.io/api/public/v1/tools/get_post_status): For submitted posts. Returns per-account receipts and failures; next list_posts or retry reported next_actions.
- [list_posts](https://post-relay.io/api/public/v1/tools/list_posts): For queue review. Returns recent post IDs and status; next get_post_status.
- [cancel_scheduled_post](https://post-relay.io/api/public/v1/tools/cancel_scheduled_post): For scheduled deliveries. Returns per-account cancellation results; next get_post_status.
- [get_trend_context](https://post-relay.io/api/public/v1/tools/get_trend_context): For sourced current evidence only. Returns scoped TikTok trending music chart or unavailable, source URLs and timestamps; next create_draft.