# Create a post

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

> Index of these docs: https://wavegrain.com/developers/llms.txt

`POST /api/v1/posts` is part of the [Posting API](/developers/posting-api). Every call needs an access key: see [Authentication](/developers/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

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Your own key for this request, so a retry never makes a second post. |

## Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `media` | string[] | no | Upload 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. |
| `slideshowId` | string | no | A 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. |
| `caption` | string | no | The caption for every network without its own in captions. On YouTube it is the description. |
| `captions` | object | no | A caption per network, such as { "threads": "..." }. Each network's own length and hashtag limits apply. |
| `cover` | object | no | Video posts only: the cover. Left out, each network picks its own (Instagram the first frame). |
| `accounts` | string[] | yes | Connected account ids from GET /api/v1/accounts. |
| `at` | string \| null | no | When to post, ISO 8601 with an offset, within the next 30 days. Left out or null: when the owner confirms. |
| `timezone` | string | no | An IANA time zone for the words of a daily limit refusal, such as Europe/Berlin. |
| `aiGenerated` | boolean | no | The images were made with AI: Instagram, Threads, Pinterest and TikTok label the post. |
| `options` | object | no | Each 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

```bash
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

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

A successful answer:

```json
{
  "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

- [List brands, groups and connected accounts](/developers/api/list-accounts): `GET /api/v1/accounts`
- [List posts](/developers/api/list-posts): `GET /api/v1/posts`
- [Get a post](/developers/api/get-post): `GET /api/v1/posts/{id}`
- [Cancel a post](/developers/api/cancel-post): `DELETE /api/v1/posts/{id}`
- [Start an image or video upload](/developers/api/create-upload): `POST /api/v1/media`
- [Get an upload](/developers/api/get-upload): `GET /api/v1/media/{id}`
- [Delete a video](/developers/api/delete-video): `DELETE /api/v1/media/{id}`
- [Finish and check a video upload](/developers/api/complete-video-upload): `POST /api/v1/media/{id}/complete`
- [Write captions](/developers/api/write-captions): `POST /api/v1/captions`
- [All endpoints](/developers/api)
