Objects

What the endpoints answer with, each described once. Lists and pages hold these in their items.

15 objects

Object

Error

errorobject
Show 6 fields
- codestring
  unauthorizedrevokedaccount_pausedplan_limitforbiddenpublish_not_allowednot_foundvalidationquota_exceededrate_limitedidempotency_conflictapproval_requiredand 3 more
- messagestring
  A sentence written for a person; safe to show.
- paramstring
  The request field, header or query parameter at fault.
- detailarray of objects
  Show 5 fields
  codestring
  messagestring
  account_idstring
  platformstring
  block_idstring
- retry_afterinteger
  Seconds to wait, on 429.
  -9007199254740991 to 9007199254740991
- neededstring
  On approval_required: whose approval is missing - "team" or "client".
  teamclient

{
  "error": {
    "code": "unauthorized",
    "message": "A sentence written for a person.",
    "param": "…",
    "detail": [
      {
        "code": "…",
        "message": "A sentence written for a person.",
        "account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
        "platform": "…",
        "block_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13"
      }
    ],
    "retry_after": -9007199254740991,
    "needed": "team"
  }
}

Object

Me

userobject
Show 1 field
- iduuid
principalobject
Show 5 fields
- kindstring
  api_keyagent
- idstring
- namestring or null
- can_publishboolean
- groups"all" or array of uuid
timezonestring
The owner's timezone (IANA name); UTC when they never chose one.
nowdatetime
The current instant, in UTC.
local_nowstring
The same instant on the owner's wall clock, with its offset.
local_weekdaystring
Today's weekday on the owner's wall clock.

{
  "user": {
    "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13"
  },
  "principal": {
    "kind": "api_key",
    "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
    "name": "Newsletter bot",
    "can_publish": false,
    "groups": "all"
  },
  "timezone": "Europe/Chisinau",
  "now": "2026-10-14T09:00:00.000Z",
  "local_now": "…",
  "local_weekday": "…"
}

Object

Group

iduuid
namestring
timezonestring
colorstring
primary_platformstring or null
xtelegraminstagramfacebooklinkedintiktokyoutube
primary_account_iduuid or null
accountsarray of objects
Show 7 fields
- iduuid
- platformstring
  xtelegraminstagramfacebooklinkedintiktokyoutube
- namestring or null
- handlestring or null
- avatar_urlstring or null
- statusstring
  activeexpiredrevokederror
- enabled_by_defaultboolean

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "name": "Newsletter bot",
  "timezone": "Europe/Chisinau",
  "color": "#4f46e5",
  "primary_platform": "x",
  "primary_account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "accounts": [
    {
      "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
      "platform": "x",
      "name": "Newsletter bot",
      "handle": "@juniper",
      "avatar_url": "https://example.com/avatar.png",
      "status": "active",
      "enabled_by_default": false
    }
  ]
}

Object

Draft

iduuid
group_iduuid or null
statusstring
draftplannedscheduledheldpublishingpublishedpartially_failedfailed
publish_statestring
idlein_progressfinished
kindstring
What the draft is; fixed once created.
postarticlereplyquotepollreelstoryrepostcomment
textstring
threadarray of strings
pollobject or null
The poll on the first post, for a poll draft.
Show 5 fields
- optionsarray of strings
- duration_daysinteger
  -9007199254740991 to 9007199254740991
- multiple_answersboolean
- quizobject
  Show 2 fields
  correct_optioninteger
  -9007199254740991 to 9007199254740991
  explanationstring
- close_after_daysinteger
  -9007199254740991 to 9007199254740991
target_urlstring or null
The post a reply, quote, repost or comment acts on.
titlestring or null
tagsarray of strings
mediaarray of MediaRef objects
planned_atdatetime or null
scheduled_atdatetime or null
published_atdatetime or null
share_urlstring or null
originobject
Show 2 fields
- kindstring
  appapiagent
- namestring or null
versioninteger
-9007199254740991 to 9007199254740991
created_atdatetime
updated_atdatetime
targetsarray of objects
Show 7 fields
- account_iduuid or null
- platformstring
  xtelegraminstagramfacebooklinkedintiktokyoutube
- statusstring or null
  pendingpublishingpublishedfailed
- textstring or null
- permalinkstring or null
- errorstring or null
- published_atdatetime or null
warningsarray of objects
"needs_person": an API key or AI agent wrote this reply to, or quote of, someone else's X post. It does not publish until a person approves it in Postacio; a key or agent cannot.
Show 2 fields
- codestring
- messagestring
approvalobject
Where the draft stands with its group's approval gate.
Show 6 fields
- requiredboolean
  The group asks for approval before a post is scheduled or published.
- statusstring
  not_requestedpendingchanges_requestedapproved
- approved_versioninteger or null
  The version the approval covers.
  -9007199254740991 to 9007199254740991
- currentboolean
  Nothing stands in the way: approval isn't required, or it covers this version.
- clientobject
  The client's half of the gate (approval views).
  Show 4 fields
  requiredboolean
  The group needs a reviewer's approval before a post is scheduled or published.
  statusstring
  Where the post stands with its client.
  not_sentsentin_reviewapprovedexempt
  approved_versioninteger or null
  The version the client approved (or that an exemption covers).
  -9007199254740991 to 9007199254740991
  currentboolean
  The client's approval isn't required, or it covers this version.
- missingarray of strings
  Which approvals still stand between this post and going out. Empty when nothing does.
  teamclient
hold_reasonstring or null
Why a "held" post is waiting: "awaiting_approval"; "needs_person" (an API key or AI agent wrote this reply to or quote of someone else's X post, and a person must approve it in Postacio); "limit" (the monthly allowance); "paused_group" or "paused_account".

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "group_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "status": "draft",
  "publish_state": "idle",
  "kind": "post",
  "text": "Hello from the Postacio API",
  "thread": [
    "…"
  ],
  "poll": {
    "options": [
      "…"
    ],
    "duration_days": -9007199254740991,
    "multiple_answers": false,
    "quiz": {
      "correct_option": -9007199254740991,
      "explanation": "…"
    },
    "close_after_days": -9007199254740991
  },
  "target_url": "https://example.com/",
  "title": "Launch week",
  "tags": [
    "…"
  ],
  "media": [
    {
      "key": "…",
      "kind": "image",
      "content_type": "image/png",
      "name": "Newsletter bot",
      "size_bytes": 1,
      "duration_sec": 1,
      "alt_text": "…"
    }
  ],
  "planned_at": "2026-10-14T09:00:00.000Z",
  "scheduled_at": "2026-10-14T09:00:00.000Z",
  "published_at": "2026-10-14T09:00:00.000Z",
  "share_url": "https://example.com/",
  "origin": {
    "kind": "app",
    "name": "Newsletter bot"
  },
  "version": -9007199254740991,
  "created_at": "2026-10-14T09:00:00.000Z",
  "updated_at": "2026-10-14T09:00:00.000Z",
  "targets": [
    {
      "account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
      "platform": "x",
      "status": "pending",
      "text": "Hello from the Postacio API",
      "permalink": "https://x.com/juniper/status/1846000000000000000",
      "error": "…",
      "published_at": "2026-10-14T09:00:00.000Z"
    }
  ],
  "warnings": [
    {
      "code": "…",
      "message": "A sentence written for a person."
    }
  ],
  "approval": {
    "required": false,
    "status": "not_requested",
    "approved_version": -9007199254740991,
    "current": false,
    "client": {
      "required": false,
      "status": "not_sent",
      "approved_version": -9007199254740991,
      "current": false
    },
    "missing": [
      "team"
    ]
  },
  "hold_reason": "…"
}

Object

enabledboolean
urlstring or null
rolestring
viewercommenterapprover
expires_atdatetime or null

{
  "enabled": false,
  "url": "https://example.com/post",
  "role": "viewer",
  "expires_at": "2026-10-14T09:00:00.000Z"
}

Object

Comment

iduuid
bodystring
authorobject
Show 2 fields
- namestring
- kindstring
  person: the owner or a team member. guest: a review-link reviewer, or someone no longer in the workspace. api / agent: an API key or AI agent.
  personguestapiagent
mentionsarray of strings
The names the comment @mentions.
thread_post_indexinteger or null
The thread post the comment is attached to; null for the whole draft, or when that post has since been removed.
0 to 49
quoteobject or null
The words in that post the thread is about, on a thread's first comment: the text selected and its offsets in the post's text when it was written. Null for a comment on the post or the draft, and on replies.
Show 3 fields
- textstring
- startinteger
  -9007199254740991 to 9007199254740991
- endinteger
  -9007199254740991 to 9007199254740991
lanestring
"team": the workspace only. "client": also shown to clients on the review link and approval view.
teamclient
reply_touuid or null
The first comment of the thread this one replies to; null for a thread's first comment.
resolvedboolean
resolved_byobject or null
Who resolved the thread and when, on a thread's first comment. Null while open.
Show 2 fields
- namestring or null
- atdatetime or null
created_atdatetime
updated_atdatetime

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "body": "Shorter hook?",
  "author": {
    "name": "Newsletter bot",
    "kind": "person"
  },
  "mentions": [
    "…"
  ],
  "thread_post_index": 0,
  "quote": {
    "text": "Hello from the Postacio API",
    "start": -9007199254740991,
    "end": -9007199254740991
  },
  "lane": "team",
  "reply_to": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "resolved": false,
  "resolved_by": {
    "name": "Newsletter bot",
    "at": "2026-10-14T09:00:00.000Z"
  },
  "created_at": "2026-10-14T09:00:00.000Z",
  "updated_at": "2026-10-14T09:00:00.000Z"
}

Object

MediaUpload

media_idstring
keystring
upload_urlstring
method"PUT"
headersmap of string

{
  "media_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "key": "…",
  "upload_url": "https://example.com/",
  "method": "PUT",
  "headers": {}
}

Object

MediaRef

keystring
1 to 512 characters
kindstring
imagevideodocument
content_typestring
1 to 200 characters
namestring
1 to 255 characters
size_bytesinteger
1 to 9007199254740991
duration_secnumber
at least 0
alt_textstring
up to 1000 characters

{
  "key": "…",
  "kind": "image",
  "content_type": "image/png",
  "name": "Newsletter bot",
  "size_bytes": 1,
  "duration_sec": 1,
  "alt_text": "…"
}

Object

MediaStatus

media_idstring
keystring
statestring
reserveduploadedreadydeleting
bytesinteger
-9007199254740991 to 9007199254740991

{
  "media_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "key": "…",
  "state": "reserved",
  "bytes": -9007199254740991
}

Object

Tag

idstring
namestring
colorstring

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "name": "Newsletter bot",
  "color": "#4f46e5"
}

Object

Slot

iduuid
labelstring
daysarray of integers
minutesinteger
0 to 1439
account_idsarray of uuid
starts_onstring or null
matches ^\d{4}-\d{2}-\d{2}$
ends_onstring or null
matches ^\d{4}-\d{2}-\d{2}$
skip_datesarray of strings

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "label": "Morning",
  "days": [
    0
  ],
  "minutes": 0,
  "account_ids": [
    "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13"
  ],
  "starts_on": "…",
  "ends_on": "…",
  "skip_dates": [
    "…"
  ]
}

Object

GoalProgress

timezonestring
The group's timezone: periods start at its midnight, weeks on Monday.
accountsarray of objects
Show 6 fields
- account_iduuid
- platformstring
  xtelegraminstagramfacebooklinkedintiktokyoutube
- namestring or null
- handlestring or null
- statusstring
- itemsarray of objects
  Show 16 fields
  kindstring
  What it counts. "original": posts, articles, quotes, polls and reels.
  originalpostarticlereplyquotepollreelstoryrepostcomment
  directionstring
  "goal": at least target. "cap": at most target.
  goalcap
  targetinteger
  -9007199254740991 to 9007199254740991
  periodstring
  dayweekmonth
  weekdaysarray of integers
  sourcestring
  Inherited from the group, or the account's own.
  groupaccount
  period_keystring
  The current period: d:2026-10-17, w:<its Monday> or m:2026-10.
  period_startdatetime
  period_enddatetime
  doneinteger
  Published in the period.
  -9007199254740991 to 9007199254740991
  plannedinteger
  Scheduled for later in the period, approved where approval is required.
  -9007199254740991 to 9007199254740991
  needs_approvalinteger
  Scheduled in the period but waiting for an approval; not part of planned.
  -9007199254740991 to 9007199254740991
  remaininginteger
  Goals: still to schedule (target - done - planned, at least 0; posts awaiting approval still count as missing). Caps: room left.
  -9007199254740991 to 9007199254740991
  statestring
  okbehindmetover_cappausedreconnectoff_dayunavailable
  paused_untilstring or null
  matches ^\d{4}-\d{2}-\d{2}$
  goal_daysobject or null
  Daily goals: this week's goal days met, gone by, and in all.
  Show 3 fields
  metinteger
  -9007199254740991 to 9007199254740991
  elapsedinteger
  -9007199254740991 to 9007199254740991
  totalinteger
  -9007199254740991 to 9007199254740991

{
  "timezone": "Europe/Chisinau",
  "accounts": [
    {
      "account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
      "platform": "x",
      "name": "Newsletter bot",
      "handle": "@juniper",
      "status": "…",
      "items": [
        {
          "kind": "original",
          "direction": "goal",
          "target": -9007199254740991,
          "period": "day",
          "weekdays": [
            0
          ],
          "source": "group",
          "period_key": "…",
          "period_start": "2026-10-14T09:00:00.000Z",
          "period_end": "2026-10-14T09:00:00.000Z",
          "done": -9007199254740991,
          "planned": -9007199254740991,
          "needs_approval": -9007199254740991,
          "remaining": -9007199254740991,
          "state": "ok",
          "paused_until": "…",
          "goal_days": {
            "met": -9007199254740991,
            "elapsed": -9007199254740991,
            "total": -9007199254740991
          }
        }
      ]
    }
  ]
}

Object

GroupSummary

fromdatetime
todatetime
totalsobject
Show 3 fields
- postsinteger
  Posts published in the window, counted once per account.
  -9007199254740991 to 9007199254740991
- metricsmap of number or null
  Each metric summed over those posts: the latest reading of each post.
- followers_changenumber or null
  Summed over the accounts with a reading at both ends.
accountsarray of objects
Show 6 fields
- account_iduuid
- platformstring
  xtelegraminstagramfacebooklinkedintiktokyoutube
- namestring or null
- postsinteger
  -9007199254740991 to 9007199254740991
- metricsmap of number or null
- followersobject
  Show 3 fields
  startnumber or null
  The first reading in the window.
  endnumber or null
  The last reading in the window.
  changenumber or null

{
  "from": "2026-10-14T09:00:00.000Z",
  "to": "2026-10-14T09:00:00.000Z",
  "totals": {
    "posts": -9007199254740991,
    "metrics": {},
    "followers_change": 0
  },
  "accounts": [
    {
      "account_id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
      "platform": "x",
      "name": "Newsletter bot",
      "posts": -9007199254740991,
      "metrics": {},
      "followers": {
        "start": 0,
        "end": 0,
        "change": 0
      }
    }
  ]
}

Object

CreatedWebhook

iduuid
urlstring
eventsarray of strings
draft.createddraft.updateddraft.planneddraft.scheduleddraft.unscheduleddraft.publisheddraft.partially_faileddraft.faileddraft.deleted
descriptionstring or null
statusstring
Paused after 25 failed attempts over at least 24 hours.
activepaused
failure_streakinteger
-9007199254740991 to 9007199254740991
failing_sincedatetime or null
last_delivery_atdatetime or null
created_atdatetime
updated_atdatetime
secretstring
The whsec_ signing secret. Shown once: store it now. An Idempotency-Key replay answers without it.

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "url": "https://example.com/post",
  "events": [
    "draft.created"
  ],
  "description": "…",
  "status": "active",
  "failure_streak": -9007199254740991,
  "failing_since": "2026-10-14T09:00:00.000Z",
  "last_delivery_at": "2026-10-14T09:00:00.000Z",
  "created_at": "2026-10-14T09:00:00.000Z",
  "updated_at": "2026-10-14T09:00:00.000Z",
  "secret": "whsec_…"
}

Object

Webhook

iduuid
urlstring
eventsarray of strings
draft.createddraft.updateddraft.planneddraft.scheduleddraft.unscheduleddraft.publisheddraft.partially_faileddraft.faileddraft.deleted
descriptionstring or null
statusstring
Paused after 25 failed attempts over at least 24 hours.
activepaused
failure_streakinteger
-9007199254740991 to 9007199254740991
failing_sincedatetime or null
last_delivery_atdatetime or null
created_atdatetime
updated_atdatetime

{
  "id": "8c1d0f3e-5b2a-4e7c-9a61-2f4b7d9e0c13",
  "url": "https://example.com/post",
  "events": [
    "draft.created"
  ],
  "description": "…",
  "status": "active",
  "failure_streak": -9007199254740991,
  "failing_since": "2026-10-14T09:00:00.000Z",
  "last_delivery_at": "2026-10-14T09:00:00.000Z",
  "created_at": "2026-10-14T09:00:00.000Z",
  "updated_at": "2026-10-14T09:00:00.000Z"
}

Ready to send your first draft?

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

Start free trial Read the guide