# Getting started with the Postally API

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.

Base URL: `https://app.postally.io/api/public/v1`

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

1. Open your Postally dashboard.
2. Go to **Settings → API Keys**.
3. Click **Create API key** and select the scopes you need — for scheduling with
   media that's `posts:write`, `media:write`, and `brands:read`.
4. 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`:

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

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

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

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

```bash
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" }
      }
    ]
  }'
```

```json
[
  { "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

- API reference — https://postally.io/docs/api
- Examples — https://postally.io/docs/examples

Reschedule with `PUT /posts/:id/date`, or remove a whole post group with
`DELETE /posts/:group`.