Skip to main content
GET
/
posts
List posts
curl --request GET \
  --url http://localhost:4100/api/v1/posts \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": "<string>",
    "workspaceId": "<string>",
    "createdByUserId": "<string>",
    "caption": "<string>",
    "scheduledAt": "2023-11-07T05:31:56Z",
    "timezone": "<string>",
    "workflowId": "<string>",
    "pendingWorkflowId": "<string>",
    "approvedByUserId": "<string>",
    "approvedAt": "2023-11-07T05:31:56Z",
    "createdViaApi": true,
    "createdViaFlatShape": true,
    "deletedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "targets": [
      {
        "id": "<string>",
        "postId": "<string>",
        "socialAccountId": "<string>",
        "captionOverride": "<string>",
        "firstComment": "<string>",
        "firstCommentError": "<string>",
        "firstCommentAttempt": 123,
        "platformOptions": {},
        "mediaIds": [
          "<string>"
        ],
        "scheduledFor": "2023-11-07T05:31:56Z",
        "publishedAt": "2023-11-07T05:31:56Z",
        "externalPostId": "<string>",
        "externalUrl": "<string>",
        "errorCode": "<string>",
        "errorMessage": "<string>",
        "attemptCount": 123,
        "lastAttemptAt": "2023-11-07T05:31:56Z",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "media": [
      {
        "postId": "<string>",
        "mediaAssetId": "<string>",
        "order": 123,
        "altText": "<string>"
      }
    ]
  }
]

Authorizations

​
Authorization
string
header
required

Your Postbreeze API key

Query Parameters

​
workspaceId
string

Optional. When set, returns posts in only this workspace. When omitted, returns posts across every workspace the API key can reach.

Response

Array of posts visible to the caller.

​
id
string

Prefixed cuid identifier.

​
workspaceId
string

Workspace this post belongs to.

​
createdByUserId
string

User id of the author.

​
status
enum<string>

Aggregate publish state. Derived from per-target statuses (PARTIALLY_PUBLISHED when some succeed and some fail).

Available options:
DRAFT,
NEEDS_APPROVAL,
SCHEDULED,
PUBLISHING,
PARTIALLY_PUBLISHED,
PUBLISHED,
FAILED,
CANCELED
​
caption
string | null

Default caption applied to every target unless overridden via targets[].captionOverride.

​
scheduledAt
string<date-time> | null

ISO-8601 publish time. Doubles as the calendar pin for drafts (set via draftScheduledAt).

​
timezone
string | null

IANA timezone the post was composed in. Cosmetic — used by the UI.

​
workflowId
string | null

Temporal workflow id driving this post's publish, when scheduled. Null on drafts and after cancellation.

​
pendingWorkflowId
string | null

Workflow id staged during the schedule transaction. Visible while a Temporal start is in flight; cleared on commit.

​
approvedByUserId
string | null

User id of the approver. Set when an NEEDS_APPROVAL post is approved.

​
approvedAt
string<date-time> | null

When the post was approved, if applicable.

​
createdViaApi
boolean

True when the post was authored by an API-key or OAuth request. Cookie-session dashboard posts are false.

​
createdViaFlatShape
boolean

True when the request used the flat platforms[] body shape. False for the nested targets[] shape and dashboard posts.

​
deletedAt
string<date-time> | null

Soft-delete timestamp. Listings and GET /posts/:id exclude rows where this is non-null.

​
createdAt
string<date-time>

When the post was created.

​
updatedAt
string<date-time>

When the post was last modified.

​
targets
object[]

One fan-out target per connected account this post publishes to.

​
media
object[]

Library media attached to the post, ordered by order. Per-target overrides on targets[].mediaIds win over this list.