/posts

Creates a post from an existing creative. A post targets one channel, so naming several channels creates several posts and the response is always a list.

Set publish_type to decide what happens: draft saves it, scheduled needs a future scheduled_at, and immediate publishes now and rejects a timestamp. It is required — there is no default, because this endpoint can publish.

Publishing is asynchronous and scheduled_at is a not before time, not an exact one: posts typically go out within a few seconds of it. Do not build a countdown that assumes the second.

Send an Idempotency-Key header on this endpoint. Publishing is not reversible, and a retry after a timeout would otherwise post twice. Reuse the same key when you retry: if the first request finished you get its original response back, and if it is still running you get 409 API_IDEMPOTENCY_KEY_IN_FLIGHT — wait a moment and retry again rather than sending a new key. Retrying with the same key is safe in every ordinary case, but it is a best-effort guard rather than a guarantee: two requests fired at the same instant can still both go through, so retry in sequence rather than in parallel.

Requires the posts:write scope.