Publish posts

A post is one piece of content with one or more targets: the accounts it publishes to. Each target has its own status, and can have its own time and settings.

Create a draft

curl https://api.nowscale.com/v1/posts \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2e0a-2f6b-4b55-9d3f-0c6c1a6c9f11" \
  -d '{
    "project_id": "PROJECT_ID",
    "title": "Behind the scenes",
    "caption": "How we shot the new collection.",
    "media_ids": ["MEDIA_ID"],
    "targets": [{ "account_id": "YOUTUBE_ACCOUNT_ID" }, { "account_id": "INSTAGRAM_ACCOUNT_ID" }]
  }'

Without scheduled_at the post stays a draft. media_ids come from media uploads; the first item leads. alt_text sets alt text per media id.

Schedule

Add scheduled_at for every target, or set it per target:

{
  "project_id": "PROJECT_ID",
  "media_ids": ["MEDIA_ID"],
  "scheduled_at": "2026-12-01T15:00:00Z",
  "targets": [
    { "account_id": "YOUTUBE_ACCOUNT_ID" },
    { "account_id": "TIKTOK_ACCOUNT_ID", "scheduled_at": "2026-12-01T18:00:00Z" }
  ]
}

Scheduling checks everything the app checks: each network's rules for the media, your plan's publication limit for that month, and the time. Schedules work in whole minutes, like the app's picker: a time before the start of the next minute (UTC) keeps the post as a draft when it has content. draft: true keeps a dated post as a draft.

When a dated post is saved as a draft instead, the create or update response says why in draft_reason: schedule_passed for a time that came too soon, publication_limit when the plan's publication limit is reached, project_restricted for an archived Project or one over the plan, network_locked, network_feature_locked or network_account_limit when the plan does not include that network, feature or account, and limit_reached for any other limit. It is null when the post was saved as you asked, and it appears only in that response.

To publish at once, create the post and call POST /v1/posts/{post_id}/publish.

Approvals

Posts follow the Project's approval policy, as in the app. A key without the posts:publish permission never schedules directly: its dated posts wait for review, whoever owns the key. With posts:publish, the policy decides (owners and admins never need review).

Send a draft for review with POST /v1/posts/{post_id}/review, and decide with /review/approve or /review/reject (the reviews:write permission). Send expected_revision to make sure you approve the version you checked.

Change, unschedule, delete

• PATCH /v1/posts/{post_id} changes only the fields you send. targets and media_ids replace the whole list.
• POST /v1/posts/{post_id}/unschedule moves a scheduled post back to drafts.
• POST /v1/posts/{post_id}/duplicate copies a post into a new draft.
• DELETE /v1/posts/{post_id} deletes it. Copies already on networks are removed where the network allows; the post shows deleting until that is done.

Network settings

network_settings applies settings to every target on a network; a target's settings override them for that account. Names are the composer's options in snake_case. For example:

{
  "network_settings": {
    "youtube": { "category_id": "22", "made_for_kids": false, "tags": ["tutorial"], "visibility": "public" },
    "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE", "disable_comment": false, "consent": true },
    "instagram": { "surface": "reel", "share_to_feed": true }
  }
}

GET /v1/networks lists each network's rules: media kinds, file types and sizes, duration, visibility choices and placements.

TikTok

TikTok requires the creator to choose a privacy level from their own account's options and to consent before each post. When your product schedules TikTok posts:

1. Show the creator's TikTok account and let them pick privacy_level from the options TikTok gives that account. There is no default.
2. Show TikTok's consent text and only then send "consent": true in the TikTok settings (for the network or the target).

A scheduled TikTok target without consent answers 400 tiktok_consent_required. Integrators are bound by the TikTok terms in the API Terms.

Follow a post

Each target in targets has a status (pending, uploading, uploaded, published, failed), the network's external_id once known, and an error_code when it failed. The post's own status sums them up: published, partial or failed once every target is done. Webhooks tell you when that happens.