List posts

List the posts in a workspace, newest first.

Last checked against the API October 10, 2026 · View as Markdown

GEThttps://studio.postprism.app/api/v1/posts

Returns posts in the workspace, most recently created first. Filter by status and page through the results with limit and offset.

Parameters

Name	In	Type	Description
`status`	query	string	Only return posts with this status. One of: `draft`, `scheduled`, `publishing`, `published`, `failed`.
`limit`	query	integer	How many posts to return. Default 50, maximum 100.
`offset`	query	integer	How many posts to skip. Default 0.
`workspace_id`	query	uuid	Act on another workspace you belong to. Defaults to the workspace your API key was created in.

Example

List scheduled posts

curl "https://studio.postprism.app/api/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer pp_live_your_api_key"

Response

200. data is an array of PostSummary. A post as returned by GET /api/v1/posts.

iduuid

The post ID.

base_contentstring

The shared draft the per-platform versions start from.

platformsstring[]

Platform keys the post targets.

platform_contentobject

Per-platform versions, keyed by platform key.

statusstring

Where the post is in its lifecycle. One of: draft, scheduled, publishing, published, failed.

scheduled_atdate-timenullable

When the post publishes, in UTC. null for drafts.

published_atdate-timenullable

When the post was published, or null.

mediaobject[]

Attached images and videos.

ai_generatedboolean

Whether the post was written with Postprism AI.

created_atdate-time

When the post was created.

200 response

{
  "data": [
    {
      "id": "3f1c2a9e-0000-4000-8000-00000000a001",
      "base_content": "Our autumn menu is here: maple oat latte, pumpkin cold brew and a new almond croissant.",
      "platforms": ["linkedin", "twitter"],
      "platform_content": {
        "linkedin": {
          "content": "Our autumn menu is here. Three new drinks, one new pastry, all made in-house at Juniper Roasters. Which one are you trying first?"
        },
        "twitter": {
          "content": "Autumn menu, now pouring. Maple oat latte first?",
          "hashtags": ["#autumnmenu", "#coffeeshop"]
        }
      },
      "status": "scheduled",
      "scheduled_at": "2026-10-16T09:30:00Z",
      "published_at": null,
      "media": [
        {
          "url": "https://…/launch-photo.webp",
          "type": "image"
        }
      ],
      "ai_generated": false,
      "created_at": "2026-10-10T14:02:11Z"
    }
  ],
  "error": null
}

Errors

Status	Message	When
401	`Invalid or revoked API key`	The `Authorization` header is missing, malformed, or the key was revoked.
429	`Too many requests`	You went over the hourly limit. See Rate limits.
404	`Workspace not found, or you are not a member of it.`	The `workspace_id` you passed (or your key’s default workspace) is not one you belong to.

PreviousPagination NextCreate a post