---
title: "Publish a completed clip to explicitly named destinations (explicit user confirmation required)"
method: POST
path: "/api/v1/publish"
---

# Publish a completed clip to explicitly named destinations (explicit user confirmation required)

`POST /api/v1/publish`

## Request

- Base URL: `https://everpop.app`
- URL: `https://everpop.app/api/v1/publish`
- Auth: HTTP bearer

Publishing is a real-world action. Before this call, show the user every exact destination, the final title/description, and visibility, then obtain an explicit go-ahead. Omitted destinations never mean all accounts.

## Request body

- object
  - `clipId` string, required
  - `destinationIds` string[], required: Exact ids returned by GET /api/v1/publish
  - `metadata` object, required
    - `title` string, required
    - `description` string, required
    - `privacyStatus` 'public' | 'unlisted' | 'private', required

## Response `200`

One result per destination; ok:true only means the request was taken. Check every posts[].status and errorCode: PUBLISHED and DELIVERED went out, FAILED and CONFLICT did not, DISMISSED was discarded; the rest are still in flight — follow them with GET /api/v1/posts?clipId=. A post still in flight that carries errorMessage is held: relay the message to the user instead of polling it.

- PublishEnvelope
  - `ok` unknown, required
  - `data` object, required
    - `clipId` string, required
    - `posts` PublishResult[], required: One result per requested destination that took the clip. Idempotent per (clip, destination): a clip already published there returns its existing post.
      - `destinationId` string, required
      - `platform` 'TIKTOK' | 'INSTAGRAM_REELS' | 'YOUTUBE_SHORTS' | 'FACEBOOK_REELS' | 'THREADS', required
      - `status` string, required: This destination's post status after the call — one of the post statuses GET /api/v1/posts reports (e.g. PUBLISHING, QUEUED, FAILED) — or CONFLICT when the destination already has a publish of this clip with different reviewed choices (see errorCode). Follow later changes with GET /api/v1/posts.
      - `currentStatus` string: When the call did not proceed because this destination already has a post for the clip: that post's status.
      - `errorCode` 'PUBLISH_INTENT_CONFLICT' | 'META_PUBLISH_HISTORY_REVIEW_REQUIRED'
      - `errorMessage` string: Customer-facing reason, when this destination did not proceed.

## Other responses

- `401`: The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.
- `402`: REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account's plan doesn't include this (API and agent access need Pro or Scale).
- `403`: reason=content_review — the clip is held for content review; or write scope/suspension.
- `404`: reason=not_found — the clip does not exist for this account.
- `409`: reason=clip_removed — the clip was removed from the library.
- `422`: reason=unknown_destination (body.destinationIds lists ids that are not connected and healthy — nothing was published), no_eligible_destination (no requested destination can take this clip, e.g. a YouTube channel other than the clip source's), clip_not_ready, or rights_unconfirmed.
- `429`: code=rate_limited: wait Retry-After (60). code=posting_cap (retryable: false, no Retry-After): an Instagram destination is at its posting-safety cap for a rolling window of days; nothing was published — tell the user.
- `503`: code=meta_publish_frozen: Instagram and Facebook publishing is paused for maintenance, and nothing in the request was published; retry after maintenance, or publish now without the Instagram and Facebook destinations. Otherwise a provider is temporarily unavailable; retry later.

---

[API](https://skmtc.dev/everpop/apis/everpop-api.md) · [All operations](https://skmtc.dev/everpop/apis/everpop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everpop/apis/everpop-api/revisions/1a9fb20867f5?raw)