Guide

Getting started

Go from zero to a scheduled post in a few minutes. This guide covers creating an API key, authenticating, uploading media, and scheduling your first post to a connected platform.

Prerequisites#

A Postally account
At least one social account connected in the dashboard (X, Instagram, LinkedIn, etc.)
Basic knowledge of REST APIs and a tool like cURL

Step 1 — Create an API key#

Open your Postally dashboard.
Go to Settings → API Keys.
Click Create API key and select the scopes you need — for scheduling with media that's posts:write, media:write, and brands:read.
Copy the token (it starts with pst_live_). It's shown only once.

Keep it secret. Use the key only from your server. Never ship it in browser or mobile client code — and revoke it from Settings → API Keys if it leaks.

Step 2 — Authenticate#

Every request needs your API key and the brand you're acting on. Find your Brand ID in the dashboard, then confirm everything is wired up with a call to /me:

cURL

curl https://app.postally.io/api/public/v1/me \
  -H "Authorization: Bearer pst_live_YOUR_API_KEY" \
  -H "x-brand-id: YOUR_BRAND_ID"

Response

{
  "organization": { "id": "org_...", "name": "Acme Inc" },
  "brand": { "id": "brand_...", "name": "Acme" },
  "user": { "id": "usr_...", "email": "you@acme.com", "name": "You" }
}

Step 3 — Upload media (optional)#

Want an image or video on your post? Upload it first and keep the id and path from the response.

cURL

curl -X POST https://app.postally.io/api/public/v1/media/upload \
  -H "Authorization: Bearer pst_live_YOUR_API_KEY" \
  -H "x-brand-id: YOUR_BRAND_ID" \
  -F "file=@./launch.png"

Response

{
  "id": "media_...",
  "name": "launch.png",
  "path": "https://cdn.postally.io/media/launch.png"
}

Step 4 — Schedule your first post#

Post to a connected account by its integration.id. Use type: "now" to publish immediately, or "schedule" with a future date.

cURL

curl -X POST https://app.postally.io/api/public/v1/posts \
  -H "Authorization: Bearer pst_live_YOUR_API_KEY" \
  -H "x-brand-id: YOUR_BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-09-01T14:30:00Z",
    "shortLink": false,
    "posts": [
      {
        "integration": { "id": "YOUR_INTEGRATION_ID" },
        "value": [
          {
            "content": "Hello from the Postally API! 🚀",
            "image": [
              { "id": "media_...", "path": "https://cdn.postally.io/media/launch.png" }
            ]
          }
        ],
        "settings": { "__type": "x" }
      }
    ]
  }'

Response

[
  { "postId": "post_...", "integration": "YOUR_INTEGRATION_ID", "group": "group_..." }
]

Don’t know your integration.id? Find it in the dashboard, or read it from the integration.id field returned by GET /posts.

Next steps#

You've authenticated, uploaded media, and scheduled a post. From here:

API referenceEvery endpoint, field, and platform setting.ExamplesMulti-platform posting in Node.js and Python.

Managing what you scheduled

Reschedule with PUT /posts/:id/date, or remove a whole post group with DELETE /posts/:group. Both are covered in Manage posts.