Create a post

Create a post with the Wavegrain Posting API: POST /api/v1/posts. Parameters, request body, responses and an example request.

POST /api/v1/posts is part of the Posting API. Every call needs an access key: see Authentication.

Needs the post permission.

Up to 35 uploaded images to up to 20 connected accounts on instagram, facebook, threads, linkedin, pinterest, tiktok, or one checked video to tiktok, instagram, facebook, threads, youtube, or a finished Wavegrain slideshow as it is (slideshowId instead of media, refused while it is being made), now or at a time, with a caption per network and each network's own settings. Every account, file and setting is checked as the send will check it, and a refusal names the account and the rule.

A video may have a cover: a time in the video (cover.atMs, used by Instagram) or an uploaded image (cover.image, used by Facebook, YouTube and Instagram). YouTube needs options.youtube with a title, a privacy and madeForKids, with no defaults. Threads videos are turned off on Wavegrain for now.

Nothing is sent yet: the account owner confirms each post in Wavegrain (the answer's confirmUrl; they are also notified). Their confirm makes one delivery per account; read their states with GET /api/v1/posts/{id}.

A key the owner trusted in Wavegrain, Settings ("Let it post without asking") sends the post at once instead, with no confirm: the answer's status is confirmed. It sends at most 100 posts in any 24 hours; past that, its post waits for the owner like any other.

TikTok posts go to the creator's TikTok inbox as drafts, finished in the TikTok app, until TikTok's Direct Post audit passes.

Send an Idempotency-Key header (1 to 255 characters) to retry safely: the same key and body answer the first result for 24 hours; another body under the key answers 409.

Parameters

NameInTypeRequiredNotes
Idempotency-KeyheaderstringnoYour own key for this request, so a retry never makes a second post.

Request body

FieldTypeRequiredNotes
mediastring[]noUpload ids from POST /api/v1/media, in post order: images, or one video (an id that starts with video_). Each upload must be finished, and a video checked with POST /api/v1/media/{id}/complete. Give media or slideshowId.
slideshowIdstringnoA finished Wavegrain slideshow to post as it is, its slides in order: from GET /api/v1/slideshows or a carousel API job. Give media or slideshowId.
captionstringnoThe caption for every network without its own in captions. On YouTube it is the description.
captionsobjectnoA caption per network, such as { "threads": "..." }. Each network's own length and hashtag limits apply.
coverobjectnoVideo posts only: the cover. Left out, each network picks its own (Instagram the first frame).
accountsstring[]yesConnected account ids from GET /api/v1/accounts.
atstring | nullnoWhen to post, ISO 8601 with an offset, within the next 30 days. Left out or null: when the owner confirms.
timezonestringnoAn IANA time zone for the words of a daily limit refusal, such as Europe/Berlin.
aiGeneratedbooleannoThe images were made with AI: Instagram, Threads, Pinterest and TikTok label the post.
optionsobjectnoEach network's own settings. Pinterest needs a board and a title; YouTube needs a title, a privacy and madeForKids. TikTok posts go to the creator's TikTok inbox as drafts for now; the creator picks the visibility in the TikTok app.

Example request

curl -X POST https://wavegrain.com/api/v1/posts \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"media":["upl_a8Zk2Qw","upl_b2Yt7Rm"],"caption":"Three ways to keep rice fluffy. Save this for later.","captions":{"threads":"Three ways to keep rice fluffy."},"accounts":["acc_4Ft7Wz"],"at":"2026-11-07T10:00:00+01:00","options":{"instagram":{"firstComment":"Recipe in the bio."}}}'

Responses

StatusMeaning
201The post, waiting for the owner's confirm, or sent at once for a trusted key.
400The body is not valid, or an account, image or setting cannot take the post; details names it.
401No access key, or an unknown, revoked or expired one
403The key lacks the permission, or the account has no active plan
409The Idempotency-Key was used for another request, or that request is still running (wait the Retry-After seconds).
429Too many requests for the key or the account, or too many posts already wait for the owner's confirm.
500Something went wrong on Wavegrain's side; try again, and send the request id if it keeps failing.

A successful answer:

{
  "id": "post_V1StGXR8_Z5jdHi6B",
  "source": "api",
  "slideshowId": null,
  "title": null,
  "status": "awaiting_confirmation",
  "confirmUrl": "/api-posts/post_V1StGXR8_Z5jdHi6B",
  "scheduledFor": "2026-11-07T09:00:00.000Z",
  "targets": [
    {
      "accountId": "acc_4Ft7Wz",
      "accountName": "Koi Kitchen",
      "network": "instagram",
      "state": "awaiting_confirmation",
      "deliveryId": null,
      "reason": null
    }
  ],
  "deliveries": []
}

More in the Posting API

Something wrong or missing? Write to support@wavegrain.com.