# Public API > Create an API key and use /api/v1 to list brands, upload inbox media, create and publish posts, and add plan slots from another system. - HTML: https://postless.app/guides/public-api - Published: 2026-09-10 - Author: Postless - Category: Product - Tags: founders, creators, agencies, teams, 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`: ```json { "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**. ```json { "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`: ```json { "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`: ```json { "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`. ```json { "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` ```json { "type": "image", "filename": "launch.png", "contentType": "image/png", "contentLength": 48210, "title": "Launch still" } ``` Video: ```json { "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. ```json { "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: ```json { "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. ```json { "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: ```json { "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`: ```json { "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. ```json { "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`: ```json { "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: ```bash 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](https://postless.app/guides/getting-started) - [Content Inbox](https://postless.app/guides/content-inbox) - [Scheduling](https://postless.app/guides/scheduling)