Statuses

Every content object walks a strict state machine. The API rejects transitions that do not appear on this diagram.

States

Status	Meaning
draft	Being edited. Not visible to reviewers, not queued to publish.
pending_review	Submitted for approval. Visible in the review queue.
approved	Approved by a reviewer. Ready to schedule.
scheduled	Has a scheduled_at in the future. The publish cron will pick it up.
publishing	The publish cron has claimed the item and is calling platform APIs.
published	At least one platform accepted the post.
failed	Every targeted platform rejected the post.
deleted	Soft-deleted. Excluded from list endpoints unless include_deleted=true.

Legal transitions

draft -> pending_review -> approved -> scheduled -> publishing -> published
                                            \-> failed
draft -> approved     (skip review, e.g. via API PATCH status=approved)
draft -> scheduled    (skip both, must include scheduled_at)
* -> deleted          (soft delete allowed from any state)

Publishing

publishing and published are set by the cron worker, not by clients. Clients move an item as far as scheduled, then wait. If you need to force-publish immediately, use POST /content/{id}/publish which runs the same pipeline synchronously (subject to platform latency).

Failures

An item enters failed only if every platform in platforms rejected the post. If one platform succeeded and one failed, the item is published and the per-platform result is visible in the response and in the content.published webhook payload.

Re-scheduling

To move a scheduled item, PATCH it with a new scheduled_at. The publish cron re-evaluates on the new slot. You cannot reschedule an item that has already reached publishing or later.

Querying by status

curl "https://app.nativpost.com/api/v1/content?status=scheduled&limit=50" \
  -H "Authorization: Bearer $NATIVPOST_API_KEY"

Pass the query multiple times to combine statuses, for example ?status=scheduled&status=publishing.