Developers

Channels

A channel is one connected social account (a Facebook Page, an Instagram Business profile, a YouTube channel, or a custom webhook). API keys can target any channel across any brand in the owning organization.

List channels

GET/api/v1/channels

bash

curl https://postme.live/api/v1/channels \
  -H "Authorization: Bearer pml_live_..."

Not paginated. Channels are hard-capped per plan, so the full list always fits in one response. Each channel carries an accepts content-capability block, audience stats, and connection health so an agent can vet it before posting.

Response: `200 OK`

json

{
  "data": [
    {
      "id": "5a1d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f",
      "platform": "meta_instagram",
      "display_name": "@outbackyak",
      "avatar_url": "https://…",
      "status": "active",
      "business_id": "9f3a4b2c-6d7e-4a1b-8c9d-0e1f2a3b4c5d",
      "business_name": "Outback Yak",
      "connected_at": "2026-05-02T11:30:00Z",
      "accepts": {
        "text_only": false,
        "images": true,
        "max_images": 10,
        "video": true,
        "multi_video": true,
        "mixed_media": true,
        "needs": "an image or video"
      },
      "stats": {
        "followers": 8421,
        "following": 312,
        "media_count": 540,
        "view_count": null,
        "as_of": "2026-06-28T06:00:00Z"
      },
      "health": {
        "token_expires_at": "2026-08-01T00:00:00Z",
        "last_refreshed_at": "2026-06-02T11:30:00Z"
      }
    },
    {
      "id": "6b2e7f8a-9b0c-4d1e-2f3a-4b5c6d7e8f90",
      "platform": "youtube",
      "display_name": "Outback Yak",
      "avatar_url": null,
      "status": "active",
      "business_id": "9f3a4b2c-6d7e-4a1b-8c9d-0e1f2a3b4c5d",
      "business_name": "Outback Yak",
      "connected_at": "2026-05-02T11:31:40Z",
      "accepts": {
        "text_only": false,
        "images": false,
        "max_images": null,
        "video": true,
        "multi_video": false,
        "mixed_media": false,
        "needs": "a video"
      },
      "stats": {
        "followers": 1290,
        "following": null,
        "media_count": 48,
        "view_count": 84021,
        "as_of": "2026-06-28T06:00:00Z"
      },
      "health": {
        "token_expires_at": null,
        "last_refreshed_at": "2026-06-20T03:00:00Z"
      }
    }
  ]
}

`accepts`: what the platform can publish

The same content rules the dashboard composer enforces — consult before creating a post to avoid 422s. text_only says whether a caption-only post (no media) can publish: true on Facebook, LinkedIn, and webhooks; false on Instagram, TikTok, and YouTube. max_images, multi_video, and mixed_media bound what media combinations the platform takes, and needs is a human-readable summary. TikTok channels additionally report direct_post: when true, posts publish straight to the profile and options.privacy_level is required; when false, videos land in the creator's TikTok inbox to finish in the app.

`stats`: audience snapshot

Best-effort, populated by a periodic account-stats poll. Any field a platform doesn't report (or that hasn't been fetched yet) is null. Read them defensively, don't assume a number.

Field	Type	Notes
`followers`	number \| null	Current follower / subscriber count.
`following`	number \| null	Accounts this channel follows, where the platform exposes it.
`media_count`	number \| null	Total posts / videos published on the channel.
`view_count`	number \| null	Lifetime view count (e.g. YouTube); `null` where not applicable.
`as_of`	RFC-3339 \| null	When this snapshot was taken. `null` if never polled.

`health`: token state

Field	Type	Notes
`token_expires_at`	RFC-3339 \| null	When the access token lapses, if the platform issues an expiry. `null` means a non-expiring or auto-refreshed grant.
`last_refreshed_at`	RFC-3339 \| null	When tokens were last refreshed, or `null` if never.

Status values

Status	Meaning
`active`	Tokens valid; the channel can publish. Only `active` channels are valid targets in `POST /posts`.
`expired`	Refresh failed. The owning user must reconnect from the dashboard.
`revoked`	Provider revoked the grant. Same fix as `expired`.
`disconnected`	User disconnected the channel in-app. Reconnecting restores it.

Get a channel

GET/api/v1/channels/{id}

One connected channel, with the same stats and health fields as the list. A channel in another organization reads as 404.

bash

curl https://postme.live/api/v1/channels/5a1d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f \
  -H "Authorization: Bearer pml_live_..."

Returns a single channel object (not wrapped in data) shaped exactly like one element of the list above.

Channels

List channels

Response: 200 OK

accepts: what the platform can publish

stats: audience snapshot