Create Post

curl --request POST \
  --url https://api.postqueen.ai/public/v1/posts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-integration-id"
      },
      "value": [
        {
          "content": "Hello world!",
          "image": []
        }
      ],
      "settings": {
        "__type": "bluesky"
      }
    }
  ]
}
'

[
  {
    "postId": "post-123",
    "integration": "integration-456"
  }
]

POST

posts

curl --request POST \
  --url https://api.postqueen.ai/public/v1/posts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-integration-id"
      },
      "value": [
        {
          "content": "Hello world!",
          "image": []
        }
      ],
      "settings": {
        "__type": "bluesky"
      }
    }
  ]
}
'

[
  {
    "postId": "post-123",
    "integration": "integration-456"
  }
]

Post type: `now`, `schedule`, or `draft`

The top-level type field controls when (and whether) the post is published:

Value	Behaviour
`"now"`	Publish immediately. `date` is ignored.
`"schedule"`	Publish at the time given in `date` (ISO 8601).
`"draft"`	Save as a draft. The post is created and stored against the integration but not scheduled or published. You can promote it to a real post later from the PostQueen UI.

Drafts are how you stage content via the API without committing to a publish time, useful for content review workflows or pre-filling a calendar from an external CMS.

posts is required for every type, drafts included. Each entry must include an integration.id, or the request returns 400 Bad Request with the message All posts must have an integration id. A draft still has to be attached to at least one channel. There is no way to create a channel-less draft via the API.

Duplicating a post

There is no dedicated duplicate / clone endpoint. To copy an existing post, fetch it with GET /posts and submit the content as a new POST /posts request.

Strip the server-managed fields from the fetched object before you re-submit. Re-sending them either causes validation errors or, worse, accidentally updates the original. At minimum drop:

id and any nested post IDs
createdAt, updatedAt, and any other timestamps
state / status / releaseId (these are assigned by the scheduler)
Anything else the API did not ask you for when you originally created the post

Then set a fresh type (now, schedule, or draft) and date, and POST the cleaned object.

Provider-Specific Settings

When creating posts, each social media platform requires different settings. The settings object must include a __type field that identifies the platform.

Supported Platforms

Platform	`__type`	Required Settings
X (Twitter)	`x`	`who_can_reply_post` (optional: `community`, `made_with_ai`, `paid_partnership`)
LinkedIn	`linkedin`	-
LinkedIn Page	`linkedin-page`	-
Facebook	`facebook`	- (optional: `url`)
Instagram (FB-linked)	`instagram`	`post_type`
Instagram Standalone	`instagram-standalone`	`post_type`
Threads	`threads`	-
Bluesky	`bluesky`	-
Mastodon	`mastodon`	-
Warpcast (Farcaster)	`wrapcast`	- (optional: `subreddit[]` for channels)
Nostr	`nostr`	-
VK	`vk`	-

Platform	`__type`	Required Settings
YouTube	`youtube`	`title`, `type`
TikTok	`tiktok`	`privacy_level`, `duet`, `stitch`, `comment`, `autoAddMusic`, `brand_content_toggle`, `brand_organic_toggle`, `content_posting_method`

TikTok honours these settings only when content_posting_method is DIRECT_POST, with UPLOAD it keeps only the post content/title. duet, stitch, and video_made_with_ai apply to video posts only; autoAddMusic to photo posts only. Every field: TikTok settings.

Platform	`__type`	Required Settings
Reddit	`reddit`	`subreddit[]` (array)
Lemmy	`lemmy`	`subreddit[]` (array)
Discord	`discord`	`channel`
Slack	`slack`	`channel`
Telegram	`telegram`	-

Platform	`__type`	Required Settings
Pinterest	`pinterest`	`board`
Dribbble	`dribbble`	`title`

Platform	`__type`	Required Settings
Medium	`medium`	`title`, `subtitle`
Dev.to	`devto`	`title`
Hashnode	`hashnode`	`title`, `tags[]`
WordPress	`wordpress`	`title`, `type`

Platform	`__type`	Required Settings
Google My Business	`gmb`	- (optional: `topicType`, `callToActionType`)
Listmonk (Newsletters)	`listmonk`	`subject`, `preview`, `list`

Platforms Without Custom Settings

These platforms only need the __type field:

{
  "settings": {
    "__type": "threads"
  }
}

Platforms: threads, mastodon, bluesky, telegram, nostr, vk

Detailed Provider Settings

Schemas and examples for each platform: Provider Settings.

Body size

Do not inline image data. This endpoint falls back to the framework’s default body limit of roughly 100 kB, which a single base64 image clears easily, and you get a 413 PayloadTooLargeError before anything is validated.The 50 MB limit you may have read about applies to the internal routes the web interface uses, not to this one.

Upload first, then reference what comes back:

# 1. upload the file
curl -X POST "https://api.postqueen.ai/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "file=@photo.jpg"

# 2. put the returned id and path in the post body's image array

Once the upload has returned an id and a path, reference those two values instead of the file itself and the post body stays inside the 100 kB limit.

Upload a File lists the accepted types, and Upload from URL does the same for media already on the web.

Next steps

Every provider setting

The full schema each platform accepts, with a worked example.

Find your channel IDs

Every connected channel, with the integration.id each post entry needs.

Upload media first

The accepted file types, and the id and path you reference back here.

Read posts back

GET /posts, which is also step one of duplicating one.

Authorizations

Authorization

string

header

required

Your PostQueen API key

Body

application/json

type

enum<string>

required

Post type. update rewrites an existing post without starting a publishing workflow.

Available options:

draft,

schedule,

now,

update

date

string<date-time>

required

Publish date in UTC ISO format

shortLink

boolean

required

Whether to use short links

Response

200 - application/json

Post created successfully

postId

string

integration

string

Getting Started

Endpoints

Posting settings by platform

Build on PostQueen

Post type: `now`, `schedule`, or `draft`

Duplicating a post

Provider-Specific Settings

Supported Platforms

Platforms Without Custom Settings

Detailed Provider Settings

Body size

Next steps

Every provider setting

Find your channel IDs

Upload media first

Read posts back

Authorizations

Body

Response

​Post type: now, schedule, or draft

​Duplicating a post

​Provider-Specific Settings

​Supported Platforms

​Platforms Without Custom Settings

​Detailed Provider Settings

​Body size

​Next steps

Every provider setting

Find your channel IDs

Upload media first

Read posts back

Authorizations

Body

Response

Post type: `now`, `schedule`, or `draft`

Duplicating a post

Provider-Specific Settings

Supported Platforms

Platforms Without Custom Settings

Detailed Provider Settings

Body size

Next steps