Posts

List, update, and manage images on generated LinkedIn drafts.

GET/api/v1/projects/:id/posts

List Posts

List generated posts for a project.

Query parameters

status - filter by post status: pending, approved, or discarded

Response 200

json

{
  "posts": [
    {
      "id": "uuid",
      "moment_id": "uuid",
      "platform": "linkedin",
      "generated_content": "Full LinkedIn post text...",
      "first_comment": "Hashtags and CTA...",
      "status": "pending",
      "publish_tool": null,
      "image_url": null,
      "created_at": "2026-05-01T10:05:00Z"
    }
  ]
}

v1 post model: One long-form LinkedIn post per extracted moment. No post_type or carousel_slides fields - these are reserved for a future API revision when Phase 10 (AI post format types) ships.

image_url values while generating: __generating__ (in progress), __error__ (failed), a normal https:// URL when ready, or null.

GET/api/v1/projects/:id/posts/:postId

Get Post

Fetch a single post. Same fields as the list endpoint.

Response 200

json

{
  "post": {
    "id": "uuid",
    "moment_id": "uuid",
    "platform": "linkedin",
    "generated_content": "...",
    "first_comment": "...",
    "status": "pending",
    "publish_tool": null,
    "image_url": null,
    "created_at": "..."
  }
}

PATCH/api/v1/projects/:id/posts/:postId

Update Post

Update a post's status and content. Optionally publish or schedule to a connected tool in the same call.

Request body (all fields optional)

json

{
  "status": "approved",
  "generated_content": "Revised content...",
  "first_comment": "Updated hashtags...",
  "image_url": "https://...",
  "provider": "buffer",
  "account_id": "optional-provider-account-id"
}

Field	Values
status	pending, approved, discarded
generated_content	String
first_comment	String or null
image_url	Valid https:// URL (SparkVox R2 or legacy Supabase public storage) or null
provider	linkedin, buffer, or publer - triggers publishing (see below)
account_id	Provider-specific account ID; omit to use the default account

Publishing behavior

Without provider - sets status: approved in SparkVox only. No post is sent anywhere.
With provider - sets status: approved and schedules the post to the connected tool. Requires a connection in Settings → Integrations. generated_content must be present when scheduling.

Response 200

Without provider: returns the updated post object.

With provider: returns the updated post object plus scheduling details:

json

{
  "id": "uuid",
  "status": "approved",
  "publish_tool": "buffer",
  "generated_content": "...",
  "scheduled_at": "2026-06-02T09:00:00.000Z",
  "job_id": "provider-job-id"
}

POST/api/v1/projects/:id/posts/:postId/generate-image

Generate Image

Start AI image generation for a post (async). Matches in-app Generate image behavior.

Request body (optional)

json

{ "post_content": "Override text to illustrate (defaults to saved generated_content)" }

Response 202

json

{ "accepted": true }

Poll GET .../posts/:postId until image_url is a normal URL (or __error__ on failure). While running, image_url is __generating__.

POST/api/v1/projects/:id/posts/:postId/upload-url

Image Upload URL

Get a presigned URL to upload your own image (JPG, PNG, GIF, WebP; max 50 MB). After uploading with PUT to upload_url, set the post image via PATCH with image_url set to public_url.

Request body

json

{
  "filename": "hero.png",
  "mime_type": "image/png",
  "file_size_bytes": 1048576
}

Field	Required
filename	Yes
mime_type	No
file_size_bytes	No

Response 200

json

{
  "upload_url": "https://...",
  "storage_path": "post-images/...",
  "content_type": "image/png",
  "public_url": "https://media.sparkvox.io/..."
}