Skip to content

Drafts

One post or thread for one or more accounts. Plan it, schedule it, publish it and send it for approval here.

12 endpoints

GET/groups/{groupId}/drafts

Drafts and posts of a group

Any key

status=failed includes partially failed posts.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

Query

  • limitinteger

    1 to 50, default 20

  • offsetinteger

    0 to 100000, default 0

  • statusstring
    draftplannedscheduledpublishingpublishedfailed
  • tagstring

    1 to 40 characters

  • account_iduuid

    Only posts aimed at, or already sent through, this connected account.

  • fromdatetime

    Only posts whose calendar time (scheduled_at, else planned_at) is at or after this. Undated drafts drop out.

  • todatetime

    Only posts whose calendar time is before this.

  • approvalstring

    Only posts at this approval status.

    not_requestedpendingchanges_requestedapproved
  • client_statusstring

    Only posts at this client status: "sent" and "in_review" are with the client; "not_sent" was never sent.

    not_sentsentin_reviewapprovedexempt
  • sortstring

    "newest" (default): newest created first. "time": by calendar time, earliest first.

    newesttime

Returns

200 with these fields; an error answers in the Error envelope.

  • itemsarray of Draft objects
  • countinteger

    -9007199254740991 to 9007199254740991

  • limitinteger

    -9007199254740991 to 9007199254740991

  • offsetinteger

    -9007199254740991 to 9007199254740991

  • nextstring or null
  • previousstring or null
curl https://postacio.com/api/v1/groups/$GROUP_ID/drafts \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
POST/groups/{groupId}/drafts

Create a draft, optionally planning, scheduling or publishing it

Any keyIdempotency-Key

Scheduling (publish_at as a time or "next-free-slot") and publish_at: "now" need publish permission. "now" answers 202 with publish_state: "in_progress"; poll the draft until it is finished.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • targetsarray of objectsrequired

    The connected accounts to publish to. At most one X account: X forbids the same post on several accounts.

    1 to 20 items

    Show 3 fields
    • account_iduuidrequired
    • textstring

      up to 90000 characters

    • optionsone of 7 shapes

      This account's publishing settings, keyed by option name. Which options exist depends on the account's platform; see the per-platform shapes. Omitted options keep their defaults.

      X options: 2 fields

      Options for an account on X.

      • replySettingsstring

        Who can reply. Applied to the first post in the native X thread. Default: "Everyone".

        EveryoneAccounts you followAccounts you mentionVerified accounts
      • dropLinksWhenOutboolean

        Post on X without the link. If this X account's X posts for the month can't cover a post with a link (after any X usage pack the group holds), it goes out with the links taken out and counts as a post without one. Default: false.

      Telegram options: 12 fields

      Options for an account on Telegram.

      • linkPreviewboolean

        Show link previews. Let Telegram render a preview for links in text messages. Postacio loads a preview of links you paste, to show it here. Default: true.

      • linkPreviewSizestring

        Preview size. Applies when linkPreview is true. Default: "Automatic".

        AutomaticSmallLarge
      • linkPreviewAboveboolean

        Show the preview above the text. Applies when linkPreview is true. Default: false.

      • linkPreviewUrlstring

        Link to preview. Preview this link instead of the first one in the text. It doesn't have to appear in the text. Applies when linkPreview is true. Default: "".

        up to 90000 characters

      • sendAsAlbumboolean

        Group media as an album. Send multiple photos and videos in one native Telegram media group. Default: true.

      • captionAboveboolean

        Put the caption above the media. Default: false.

      • spoilerboolean

        Hide photos and videos behind a spoiler. Readers tap to reveal them. Files are not affected. Default: false.

      • buttonsarray of objects

        Link buttons. Buttons that open a link, under the last message of the post. An album can't carry them, so a post that ends with one needs "Group media as an album" off. Default: [].

        up to 6 items

        Show 2 fields
        • textstringrequired

          1 to 40 characters

        • urlstringrequired
      • silentboolean

        Send silently. Subscribers get the post without a notification sound. Default: false.

      • protectContentboolean

        Protect content. Prevent forwarding and saving in Telegram where the destination supports it. Default: false.

      • deleteAfterstring

        Remove after. Remove the post from the channel after this long. Telegram lets a bot remove its post for 48 hours. Default: "Never".

        Never1 hour6 hours12 hours24 hours47 hours
      • topicIdstring

        Forum topic. Only for a group with Topics turned on. In Telegram, open the topic and copy its link. Leave it empty to post in the group's main chat. Default: "".

        up to 90000 characters

      Instagram options: 11 fields

      Options for an account on Instagram.

      • aspectRatiostring

        Aspect ratio. Photos are center-cropped to this ratio at publish. Original keeps your photo and only trims it if Instagram would reject it (accepted range: 4:5 to 1.91:1). Applies when the draft is a Post (not a Reel or Story). Default: "Original".

        OriginalSquare (1:1)Portrait (4:5)Landscape (16:9)
      • feedMediastring

        Choose media type. Choose which to publish when your tray contains both. Video publishes as a Reel; Photo carousel posts your photos; Photos & video posts a mixed carousel of both. Applies when the draft is a Post and its media mixes a video and photos. Default: "Video (publishes as Reel)".

        Video (publishes as Reel)Photo carouselPhotos & video (mixed carousel)
      • shareReelToFeedboolean

        Also show Reel in feed. Applies when the draft is a Reel. Default: true.

      • collaboratorsarray of strings

        Collaborators. Up to 3 accounts invited to co-author this post. It shows on their profiles once they accept the invite in Instagram. Not on Stories or trial reels. Applies when the draft is a Post or a Reel (not a Story or a trial reel). Default: [].

        up to 3 items

      • aiGeneratedboolean

        Add the AI info label. Tells people this post was made or edited with AI, with Instagram's AI info label. Applies when the draft is a Post or a Reel (not a Story). Default: false.

      • trialReelboolean

        Trial reel. Shows the Reel to people who don't follow you first, so you see how it does before your followers do. Only for accounts Instagram has given trial reels to. Applies when the draft is a Reel. Default: false.

      • trialGraduationstring

        Share with followers. Manually: you decide in the Instagram app when your followers see it. Automatically: Instagram shares it with them if it does well with non-followers. Applies when the draft is a Reel and trialReel is true. Default: "Manually in Instagram".

        Manually in InstagramAutomatically if it performs well
      • commentsarray of strings

        Comments Postacio posts under the post, in order, right after it publishes. Not on Stories.

        up to 50 items

      • firstCommentstringdeprecated

        Retired: use comments. Published only when comments is empty.

        up to 90000 characters

      • altTextstringdeprecated

        Retired: set alt_text on the media item instead. Reaches only a lone feed photo that has none.

        up to 90000 characters

      • userTagsarray of objects

        People tagged in the post. On a Post each tag sits on one photo (default: the first, at its centre), up to 20 per photo; on a Reel the tags go on the Reel. Not on Stories.

        up to 200 items

        Show 4 fields
        • usernamestringrequired

          The tagged account's public Instagram username.

          matches ^@?[A-Za-z0-9._]{1,30}$

        • photointeger

          Which of the post's photos the tag is on, counted from 1 in media order; videos are not counted. Ignored on a Reel.

          1 to 10

        • xnumber

          From the photo's left edge, 0 to 1. Ignored on a Reel.

          0 to 1

        • ynumber

          From the photo's top edge, 0 to 1. Ignored on a Reel.

          0 to 1

      Facebook options: 4 fields

      Options for an account on Facebook.

      • articleUrlstring

        Link URL. Publish a native Facebook link preview. Link posts cannot include separate media. Applies when the draft is a Post (not a Reel, Story or Comment). Default: "".

        up to 90000 characters

      • feedMediastring

        Choose media type. Choose which to publish when your tray contains both. Video posts the clip; Photos posts the carousel. Applies when the draft is a Post and its media mixes a video and photos. Default: "Video".

        VideoPhotos
      • commentsarray of strings

        Comments Postacio posts under the post, in order, right after it publishes. Not on Stories.

        up to 50 items

      • audienceobject

        Who the Page post is for. Posts only; omitted fields keep their defaults.

        Show 8 fields
        • modestring

          "everyone"; "preferred" guides News Feed distribution; "restricted" hides the post from anyone outside it.

          everyonepreferredrestricted
        • ageMininteger

          Restricted audiences take only 13, 15, 18, 21, 25.

          13 to 65

        • ageMaxinteger

          Preferred audiences only.

          13 to 65

        • countriesarray of strings

          Two-letter country codes.

          up to 25 items

        • genderstring

          Preferred audiences only.

          allmenwomen
        • educationStatusstring

          Preferred audiences only.

          allhigh-schoolundergraduatealum
        • relationshipStatusstring

          Preferred audiences only.

          allsinglein-a-relationshipmarriedengaged
        • collegeYearsarray of integers

          Preferred audiences only.

          up to 20 items

      LinkedIn options: 7 fields

      Options for an account on LinkedIn.

      • visibilitystring

        Visibility. Default: "Public".

        PublicConnections only
      • postFormatstring

        Post format. Default: "Post".

        PostArticle / link
      • feedMediastring

        Choose media type. Choose which to publish when your tray contains both. Video posts the clip; Images creates a native multi-image post (up to 20 images). Applies when postFormat is "Post" and the media mixes a video and images. Default: "Video".

        VideoImages
      • documentTitlestring

        Document title. LinkedIn shows this title above a document post's pages. Leave it empty to use the file's name. Applies when postFormat is "Post" and the media is a document (PDF, PowerPoint or Word). Default: "".

        up to 400 characters

      • articleUrlstring

        Article URL. LinkedIn uses this URL as the source of its native article preview. Applies when postFormat is "Article / link". Default: "".

        up to 90000 characters

      • articleTitlestring

        Article title. Required because LinkedIn's Posts API does not scrape the URL for preview metadata. Applies when postFormat is "Article / link". Default: "".

        up to 400 characters

      • articleDescriptionstring

        Article description. Applies when postFormat is "Article / link". Default: "".

        up to 4086 characters

      TikTok options: 11 fields

      Options for an account on TikTok.

      • privacyLevelstring or ""

        Who can view the post: PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR or SELF_ONLY. Required before scheduling or publishing; there is no default. The account must offer the level when it is checked with TikTok (a private account cannot post to everyone).

      • policyConsentboolean

        Required true before scheduling or publishing; there is no default. Set it only once the person posting has answered disclosure and agreed to TikTok's Music Usage Confirmation (https://www.tiktok.com/legal/page/global/music-usage-confirmation/en), and to its Branded Content Policy (https://www.tiktok.com/legal/page/global/bc-policy/en) when brandedContent is true.

      • allowCommentboolean

        Let people comment. Default false. Refused if the account turned comments off.

      • allowDuetboolean

        Let people Duet the video. Videos only. Default false. Refused if the account turned Duet off.

      • allowStitchboolean

        Let people Stitch the video. Videos only. Default false. Refused if the account turned Stitch off.

      • disclosureboolean

        The post promotes a brand, product or service (TikTok's commercial content disclosure). Default false. When true, set yourBrand, brandedContent or both.

      • yourBrandboolean

        Promotes your own business; TikTok labels it 'Promotional content'.

      • brandedContentboolean

        A paid partnership promoting a third party; TikTok labels it 'Paid partnership'. Cannot be SELF_ONLY.

      • aiGeneratedboolean

        Label the post as AI-generated content. Default false.

      • autoAddMusicboolean

        Let TikTok add recommended music. Photo posts only. Default false.

      • photoTitlestring

        A photo post's title, at most 90 characters; the post's text is its description. Ignored on a video.

        up to 90 characters

      YouTube options: 6 fields

      Options for an account on YouTube.

      • titlestring

        The video's title, at most 100 characters, no < or >. Required before scheduling.

        up to 100 characters

      • privacystring or ""

        Who can watch: public, unlisted or private. Default public (an empty string means the default).

      • madeForKidsstring

        Whether the video is made for kids (COPPA): yes or no. Required before scheduling; there is no default.

        yesno
      • tagsarray of strings

        Tags, at most 500 characters in all (a tag with a space counts its quotes).

        up to 100 items

      • categoryIdstring

        YouTube's category id: 1 Film & Animation, 2 Autos & Vehicles, 10 Music, 15 Pets & Animals, 17 Sports, 19 Travel & Events, 20 Gaming, 22 People & Blogs, 23 Comedy, 24 Entertainment, 25 News & Politics, 26 Howto & Style, 27 Education, 28 Science & Technology, 29 Nonprofits & Activism. Default "22" (People & Blogs).

        1210151719202223242526and 3 more
      • paidPromotionboolean

        The video includes a paid product placement, sponsorship or endorsement; YouTube tells viewers so. Default false.

  • textstring

    The post. Use thread instead for a multi-post thread.

    up to 10000 characters

  • threadarray of strings

    Posts of a thread, in order.

    1 to 50 items

  • titlestring

    A working title shown in Postacio; never published.

    up to 140 characters

  • mediaarray of MediaRef objects

    up to 20 items

  • tagsarray of strings

    up to 20 items

  • auto_numberboolean

    Prefix each thread post with 1/, 2/ ...

  • plan_at"next-free-slot" or datetime

    Put the draft on the calendar without publishing it.

  • publish_at"now" or "next-free-slot" or datetime

    "now", "next-free-slot", or an ISO datetime to schedule.

  • jitter_minutesinteger

    0 to 15

  • kindstring

    What the draft is; fixed once created. post (default, any network); reel and story (Instagram, Facebook; need a video, or media for a story); poll (X, LinkedIn, Telegram; send poll, and the text is the question); article (one X account with X Premium); reply and quote (one X account; send target_url); repost (one X or LinkedIn account; send target_url).

    postarticlereplyquotepollreelstoryrepost
  • pollobject

    The poll, with kind "poll". It goes on the first post; the text is its question.

    Show 5 fields
    • optionsarray of stringsrequired

      The answers, in order. X and LinkedIn take 2-4 (X 25 characters each, LinkedIn 30); Telegram alone takes up to 12 of 100.

      2 to 12 items

    • duration_daysinteger

      How long it runs. X: 1, 3 or 7. LinkedIn: 1, 3, 7 or 14. Telegram reads close_after_days instead. Default 1.

      1 to 14

    • multiple_answersboolean

      Telegram only: readers may pick more than one answer. Not with quiz.

    • quizobject

      Telegram only: make the poll a quiz with one right answer.

      Show 2 fields
      • correct_optionintegerrequired

        The right answer, as an index into options.

        0 to 11

      • explanationstring

        Shown after someone answers.

        up to 200 characters

    • close_after_daysinteger

      Telegram only: close the poll this many days after it is posted. Omitted, it stays open.

      1 to 14

  • target_urlstring

    The post a reply, quote or repost acts on: a link to an X post (reply, quote, an X repost) or a LinkedIn post (a LinkedIn repost).

    up to 600 characters

Returns

201 with a Draft object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "Hello from the Postacio API",
    "targets": [
      {
        "account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13"
      }
    ],
    "publish_at": "next-free-slot"
  }'
GET/groups/{groupId}/drafts/{draftId}

One draft

Any key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Returns

200 with a Draft object; an error answers in the Error envelope.

curl https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
PATCH/groups/{groupId}/drafts/{draftId}

Change a draft (last write wins)

Any key

A scheduled draft needs publish permission; a publishing or published one answers 409.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Body

  • textstring

    The post. Use thread instead for a multi-post thread.

    up to 10000 characters

  • threadarray of strings

    Posts of a thread, in order.

    1 to 50 items

  • titlestring or null

    up to 140 characters

  • targetsarray of objects

    The connected accounts to publish to. At most one X account: X forbids the same post on several accounts.

    1 to 20 items

    The same fields as in Create draft.

  • mediaarray of MediaRef objects

    up to 20 items

  • tagsarray of strings

    up to 20 items

  • auto_numberboolean

    Prefix each thread post with 1/, 2/ ...

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X PATCH https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello again from the Postacio API",
    "tags": [
      "launch"
    ]
  }'
DELETE/groups/{groupId}/drafts/{draftId}

Delete a draft

Any key

Anything past a plain draft (scheduled, held, published or failed) needs publish permission; a publishing one answers 409.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Returns

204 with no body; an error answers in the Error envelope.

curl -X DELETE https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
POST/groups/{groupId}/drafts/{draftId}/plan

Put a draft on the calendar without publishing it

Any keyIdempotency-Key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • plan_at"next-free-slot" or datetimerequired

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/plan \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "plan_at": "2026-10-20T09:00:00+02:00"
  }'
DELETE/groups/{groupId}/drafts/{draftId}/plan

Take a draft off the calendar

Any key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X DELETE https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/plan \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
POST/groups/{groupId}/drafts/{draftId}/schedule

Schedule a draft to publish

Needs publishingIdempotency-Key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • publish_at"next-free-slot" or datetimerequired
  • jitter_minutesinteger

    0 to 15

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/schedule \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "publish_at": "2026-10-20T09:00:00+02:00",
    "jitter_minutes": 5
  }'
DELETE/groups/{groupId}/drafts/{draftId}/schedule

Unschedule, keeping the date as planned

Needs publishing

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X DELETE https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/schedule \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
POST/groups/{groupId}/drafts/{draftId}/publish

Publish now

Needs publishingIdempotency-Key

Answers at once with publish_state: "in_progress"; poll the draft until it is finished. Also spends the owner's publish budget (20 a minute).

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Returns

202 with a Draft object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/publish \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/groups/{groupId}/drafts/{draftId}/approval

Ask for approval, approve, or request changes

Any keyIdempotency-Key

request needs write access; approve and request_changes need publish permission. approve takes expected_version, the version you reviewed: a newer one is 409. Approving a post held for approval sends it out. request_changes needs a comment, posted as a review comment.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • actionstringrequired

    "request" asks the group's approvers; "approve" and "request_changes" decide.

    requestapproverequest_changes
  • messagestring

    A note with a request (at most 500 characters).

    up to 500 characters

  • commentstring

    What needs to change (required for request_changes), or a note with an approval.

    up to 2000 characters

  • expected_versioninteger

    To approve: the draft version you reviewed, from get_draft. A newer version is refused.

    -9007199254740991 to 9007199254740991

Returns

200 with a Draft object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/approval \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "approve",
    "expected_version": 7
  }'
POST/groups/{groupId}/drafts/{draftId}/share

Turn the review link on or off

Any keyIdempotency-Key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • draftIduuidrequired

    A draft id.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • enabledbooleanrequired
  • rolestring
    viewercommenterapprover
  • expirystring
    never24h7d30d

Returns

200 with a Share object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/drafts/$DRAFT_ID/share \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "enabled": true,
    "role": "approver",
    "expiry": "7d"
  }'

Ready to send your first draft?

Start your free trial, create a key in Settings, and call the API in a minute.

Start free trialRead the guide