# Publishing and scheduling

An AiVideoEditor post has a versioned draft and independent deliveries for its selected
accounts. Draft saving is permissive; successful saving does not establish that
every destination is publishable.

## Prepare a post

1. Read `/api/v1/accounts` and `/api/v1/capabilities` with the intended key.
2. Upload and finalize any required [media](/docs/media).
3. Create a draft with `POST /api/v1/posts`, or edit with `PATCH /api/v1/posts/{id}`.
   Supply the current `expectedVersion` on edits and preserve the returned version.
4. Set destination format and explicit per-account variant overrides where needed.
   The [API reference](/docs/api) defines the request fields.
5. Validate with `POST /api/v1/posts/{id}/validate`. HTTP 200 may contain
   `valid: false`; inspect every issue before submitting. Invalid accounts are not
   silently removed from the audience.

## Publish now or later

`POST /posts/{id}/publish` submits the current draft. `POST /posts/{id}/schedule`
requires `scheduledAt`, `timezone` and `expectedVersion`. The scheduled instant
must be future and within 90 days. Store a UTC ISO timestamp and a separate IANA
display timezone; resolve daylight-saving ambiguities before sending.

Use a distinct `Idempotency-Key` for each new mutation. Retain that key and exact
request body before sending. Following a timeout, replay the identical request
with the same key. Change the key only when intentionally requesting a new
operation. A stale draft edit or schedule returns `revision_conflict`; reread and
review the latest content rather than overwriting it blindly.

A `202` response means accepted for dispatch. It is not evidence of publication.
Record delivery IDs and observe `GET /posts/{id}` or signed customer webhooks.
Use bounded polling with increasing delays; stop for terminal results or a human
handoff rather than looping indefinitely.

## Per-destination outcomes

Deliveries can settle independently. One destination may publish while another
needs reconnection or consent. Show each state and native post link when present.
Retry only an eligible known failure using `POST /deliveries/{id}/retry`.
Successful destinations must not be recreated to recover a failed one. An unknown
external outcome needs reconciliation or review, not a fresh submission.

Cancel with `POST /deliveries/{id}/cancel` while work remains safely unclaimed.
`too_late_to_cancel` means submission has progressed beyond safe cancellation;
it does not mean the external post has been removed.

## TikTok human review

Read `/accounts/{id}/tiktok/settings` for current creator settings and available
privacy choices. A settings read or a draft save does not provide consent.
`consent_required` includes a safe `requiresAction` handoff to the authenticated
composer. An authorized person reviews the exact video, caption and destination
and explicitly confirms the required choices there. Product keys and MCP tools
cannot confirm on their behalf. Content or identity changes require fresh review.
The handoff grants no membership or access by itself.


## Composer controls

Use **Add media** to upload a file or choose an existing library item. The caption is shared until **Customize content** creates an account-specific variant. Emoji and hashtag tools insert ordinary text at the cursor.

**Posting options** groups settings for the selected account. Required choices stay visible; optional groups remain collapsed. Changes apply only to that account. **Preview** shows the effective draft without saving or submitting it, including incomplete drafts; native platform presentation can differ.

Use private asset references for scheduled covers and thumbnails. Public URL alternatives must remain reachable at delivery time. Subtitle content is stored with the immutable settings rather than depending on a temporary local file. LinkedIn document upload currently accepts PDF; Office formats remain restricted until signature validation is implemented.

See the [capabilities reference](/docs/capabilities) for canonical controls and integration limits. New format and confirmation behavior requires the corresponding database migrations before deployment.
