Public API

Use the public API when another system should send content into Postless without opening the dashboard.

The API can manage content on a brand that already exists. Keys cannot create a brand, change brand settings, connect social accounts, change billing, delete your account, or create or revoke API keys.

Create a key

1. Open Settings → API keys.
2. Name the key.
3. Choose permissions. Defaults are List brands, Add inbox items, and Create posts. Read posts and Add plan slots are off unless you turn them on. Turn on Publish posts only if the key should publish immediately.
4. Optionally limit the key to specific brands. Leave them unchecked to allow every finished brand you own. Incomplete and archived brands are never reachable.
5. Click Create key and copy the secret. It is shown once. Disable or revoke later from the same Settings page. The public API cannot mint or revoke keys.

Call the API with:

Authorization: Bearer pl_...

x-api-key: pl_... also works. Call from your server, not from a browser page.

Base URL: https://dashboard.postless.app (or your Postless host).

Permissions

Permission	What it allows
brands:read	List brands and connected accounts (providerAccountId)
inbox:write	Add an inbox item, including image/screenshot/video upload
posts:write	Create a post, and attach inbox media
posts:read	Get a post, including attached media
posts:publish	Publish a draft (POST .../posts/:id/publish) or create with publishNow: true
plans:write	Add a slot to the current plan

Same subscription and usage limits as the dashboard apply. Keys are also limited to 60 requests per minute.

Bodies are JSON. Most errors look like { "error": "…" }. Some also include code.

Errors

Status	Meaning
400	Invalid JSON body
401	Missing or invalid key
402	No active subscription (subscription_required)
403	missing_permission, brand_not_allowed, or email_not_verified
404	Unknown brand, post, inbox item, or plan. Also used for unfinished or archived brands
409	Attach on a non-draft, publish when already published, or upload object missing
422	Invalid body, or the post is not ready to schedule/publish
429	Key rate limit (rate_limit_exceeded) or usage cap (limit_exceeded with limit, used, cap)
502	Upstream publish failed

Inbox JSON create also uses 422 with code: use_upload_url (image/screenshot/video) or generated_not_allowed.

List brands

GET /api/v1/brands — permission brands:read

200:

{
  "brands": [{ "id": "11111111-1111-4111-8111-111111111111", "name": "Acme" }]
}

Add an inbox item

POST /api/v1/brands/:brandId/inbox — permission inbox:write

JSON create matches dashboard Add New for text types. Send type plus at least one of title, rawContent, or sourceUrl (except Work Update and Customer Feedback, which may be empty like the dashboard). sourceUrl is optional on Quick Note, Content Idea, Article, and Link.

{
  "type": "link",
  "title": "We shipped search",
  "rawContent": "Notes for later drafts.",
  "sourceUrl": "https://example.com/search"
}

type is one of text, link, article, idea, work_update, feedback.

Work update uses the same rawContent string as the dashboard (What happened plus What I learned:). Feedback uses rawContent plus optional metadata.source:

{
  "type": "feedback",
  "rawContent": "Checkout felt slow on mobile",
  "metadata": { "source": "App Store" }
}

generated is created only by AI in the dashboard, not Add New and not this endpoint. Image, screenshot, and video use the upload flow below, not this JSON body (422 use_upload_url).

201:

{
  "id": "…",
  "brandId": "…",
  "type": "link",
  "title": "We shipped search",
  "rawContent": "Notes for later drafts.",
  "sourceUrl": "https://example.com/search",
  "mediaPath": null,
  "mediaType": null,
  "uploadStatus": null,
  "createdAt": "2026-09-10T12:00:00.000Z"
}

Feedback includes metadata when you send it. Media types set mediaPath, mediaType, and uploadStatus after the upload flow.

List connections

GET /api/v1/brands/:brandId/connections — permission brands:read

Returns ACTIVE social accounts for the brand owner. Use providerAccountId as publishConnectionIds / accountIds.

{
  "connections": [
    {
      "providerAccountId": "acc_123",
      "platform": "linkedin",
      "username": "acme",
      "status": "ACTIVE"
    }
  ]
}

Upload inbox media

Same three steps as dashboard Add New: one signed URL, PUT the file, confirm. One file per request.

• Images / screenshots: PNG, JPEG, WEBP, or GIF, 10 MB or smaller. type is image or screenshot.
• Video: MP4 (video/mp4), 100 MB or smaller. type is video. Confirm does not run image compression or vision.

The signed PUT is locked to contentLength, so a larger file is rejected by storage.

1. POST /api/v1/brands/:brandId/inbox/upload-url — inbox:write

{
  "type": "image",
  "filename": "launch.png",
  "contentType": "image/png",
  "contentLength": 48210,
  "title": "Launch still"
}

Video:

{
  "type": "video",
  "filename": "clip.mp4",
  "contentType": "video/mp4",
  "contentLength": 2482100
}

201: { inboxItemId, uploadUrl, path, token }.

2. PUT the file bytes to uploadUrl with the same Content-Type. The body must be exactly contentLength bytes.
3. POST /api/v1/brands/:brandId/inbox/:inboxItemId/confirm-upload — inbox:write

200 is the same inbox item shape as JSON create. Images then compress and run vision in the background (vision waits until compression finishes). Videos skip both.

Confirm on a still includes metadata.visionStatus: "pending". Attach and publish do not wait for vision — they only copy the file. Vision is a background description for dashboard Create Post / planner generate. The public API has no inbox GET, so you cannot poll status from a key. A missing description does not fail the upload.

Confirm errors: 404 unknown item, 400 no pending upload, 409 object missing in storage.

AI generate image/video/carousel stays in the dashboard. The public API does not generate media.

Attach inbox media to a draft

PUT /api/v1/brands/:brandId/posts/:postId/media — permission posts:write

The post must be a draft. This does not upload a file and does not publish. It copies inbox items you already uploaded onto the post.

{
  "inboxItemIds": ["…"],
  "accountIds": ["acc_123"]
}

Omit accountIds to attach to every compatible account in the post’s publish set (brand defaults, or publishConnectionIds on the post). Stills skip YouTube. Videos attach to YouTube. If nothing compatible remains, 422. Cap is 20 inbox items.

200 is the post object plus:

{
  "attachedAccountIds": ["acc_123"],
  "skippedAccountIds": ["yt_456"]
}

skippedAccountIds are YouTube (or other video-only) accounts skipped for stills. That does not remove them from publish targets. If YouTube is still a target and you only attached stills, publish will fail until you attach a real video or drop YouTube from publishConnectionIds.

409 if the post is not a draft. 422 if an inbox id is missing or has no file.

Create a post

POST /api/v1/brands/:brandId/posts — permission posts:write

This is the same as Create Post in the dashboard: you send finished copy. It is not AI generation. Posts are always approved. Brand “require approval” does not apply.

{
  "topic": "Search is live",
  "body": "We shipped search today. Here is what changed.",
  "platforms": ["linkedin", "x"],
  "scheduledAt": "2026-09-12T10:00:00.000Z",
  "publishNow": false
}

Field	Notes
topic	Optional
body	Required to schedule or publish now. Omit it to create an empty draft
platforms / publishConnectionIds	Optional. Defaults to the brand’s publishing defaults
scheduledAt	Future ISO time → queued. Omit → draft
inboxItemIds	Optional. After the file is in the inbox, attach those items in this same call
accountIds	Optional with inboxItemIds. Same targeting as PUT attach
publishNow	true publishes this new post in the same request (after attach, if any). Needs posts:publish. Ignores scheduledAt

Create → attach → publish in one JSON call after you have already uploaded the file:

{
  "body": "We shipped search today.",
  "inboxItemIds": ["…"],
  "publishNow": true
}

publishNow on create is for a new post. POST .../posts/:postId/publish is for a draft that already exists (you attached media later, or you created the draft first). Neither attach endpoint publishes. Same publish gates as the dashboard (Instagram needs media, YouTube needs video, TikTok rejects mixed image+video).

201:

{
  "id": "…",
  "brandId": "…",
  "topic": "Search is live",
  "body": "We shipped search today. Here is what changed.",
  "status": "queued",
  "approved": true,
  "scheduledAt": "2026-09-12T10:00:00.000Z",
  "publishConnectionIds": ["…"],
  "media": [{ "path": "…/launch.png", "type": "image/png" }],
  "createdAt": "2026-09-10T12:00:00.000Z"
}

media[] items are { path, type } and thumbnailPath when a cover exists. When inboxItemIds is sent, the response also includes attachedAccountIds and skippedAccountIds. Attach failure after create returns that error plus the created post so you can retry PUT .../media.

Publish a draft

POST /api/v1/brands/:brandId/posts/:postId/publish — permission posts:publish

Publishes an existing draft immediately. Same gates as publishNow on create. 200 is the post object (status typically published or failed). 409 if it is already published. 422 if caption or media gates fail. 502 if the publisher rejects the post.

Get a post

GET /api/v1/brands/:brandId/posts/:postId — permission posts:read

Returns the same post object as create.

Add a plan slot

POST /api/v1/brands/:brandId/plan/slots — permission plans:write

Adds one idea to the plan that already exists. It does not regenerate the week.

{
  "topic": "What we learned shipping search",
  "day": "monday",
  "format": "hot_take",
  "scheduledAt": "2026-09-15T10:00:00.000Z"
}

topic is required. day, format, and scheduledAt are optional. Omit day to use today. A named day is the next occurrence of that weekday (today rolls to next week). Omit format to use insight. Multiple cards can share the same day. 404 if the brand has no active plan.

201:

{
  "id": "…",
  "planId": "…",
  "day": "monday",
  "topic": "What we learned shipping search",
  "format": "hot_take",
  "scheduledAt": "2026-09-15T10:00:00.000Z",
  "slotDate": "2026-09-15"
}

Example

List brands, then create a draft:

curl https://dashboard.postless.app/api/v1/brands \
  -H "Authorization: Bearer pl_YOUR_KEY"

curl https://dashboard.postless.app/api/v1/brands/BRAND_ID/posts \
  -H "Authorization: Bearer pl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"Search is live","body":"We shipped search today."}'

Related

• Getting started
• Content Inbox
• Scheduling