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

Before you begin

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.

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 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 -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"

{
  "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 -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.

You're live!

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

• API Reference — every endpoint, field, and platform setting
• Examples — multi-platform posting in Node.js and Python
• Reschedule with PUT /posts/:id/date or remove with DELETE /posts/:group