API documentation

The Brandefer API lets your systems do what your team does in the app: list a project's connected social accounts, upload media, and create posts that go out as drafts, on a schedule, or immediately. Platform-specific mechanics such as Instagram container processing, TikTok upload flows, LinkedIn asset uploads and token refresh are handled by Brandefer; the API accepts text and media and reports per-channel results.

All requests and responses use JSON, except media uploads, which take the file bytes as the request body. The base URL is:

https://brandefer.com/api/v1

Every request carries an API key in the Authorization header:

Authorization: Bearer bfr_YOUR_KEY

Keys are created in the app and shown once, at creation. There are two scopes:

Each key carries a set of capabilities chosen at creation. A request that needs a capability the key does not have is refused with status 403.

Keys can be revoked at any time from the same card. A key also stops working automatically when the person who created it loses access to the project or organization.

Errors return a JSON body of the form { "error": "human-readable reason" } with a matching status code:

A channel is a connected social account inside a project. Channel ids are the addresses that posts are sent to.

Requires the read capability. Returns:

{
  "channels": [
    {
      "id": "5b2e…",            // use this in channelIds when creating posts
      "platform": "linkedin",   // facebook · instagram · linkedin · x · tiktok · youtube
      "name": "Acme Inc",
      "username": "acme",       // handle where the platform has one
      "status": "active"        // active · expired (needs reconnecting in the app)
    }
  ]
}

Media is uploaded before it is referenced by a post. The request body is the file itself, sent with its real Content-Type; there is no multipart or base64 wrapping.

Requires the media capability. Accepted types are image/jpeg, image/png, image/webp, image/gif and video/mp4, up to 100 MB.

curl -X POST "https://brandefer.com/api/v1/media?filename=hero.png" \
  -H "Authorization: Bearer bfr_YOUR_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @hero.png

Returns status 201:

{
  "mediaIds": ["9f41…"],       // pass through to a post's mediaIds
  "url": "https://media.brandefer.com/…",
  "mimeType": "image/png"
}

One request creates a post across any number of the project's channels. The shared text is used for every channel unless a per-channel override replaces it. Every selected channel must end up with text or at least one media attachment.

curl -X POST https://brandefer.com/api/v1/posts \
  -H "Authorization: Bearer bfr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Shared text for every channel",
    "channelIds": ["5b2e…"],
    "mode": "schedule",
    "scheduledAt": "2026-08-20T15:00:00+03:00",
    "mediaIds": ["9f41…"]
  }'

Returns status 201:

{
  "postId": "ecf1…",
  "mode": "schedule",
  "status": "scheduled"        // draft · scheduled · publishing
}

Publishing is asynchronous. When mode is now the request returns at once with status publishing while delivery happens in the background; poll the post endpoint below for the outcome. Multi-image posts become the appropriate format per network: a carousel on Instagram, a multi-image post on LinkedIn, an album on Facebook. A single video sent to Instagram publishes as a Reel.

Returns the post and the state of each channel it targets, including the live URL and the platform's own post id once a channel has published.

Requires the read capability. Returns:

{
  "postId": "ecf1…",
  "status": "published",       // draft · scheduled · publishing · published · partial · failed
  "text": "…",
  "scheduledAt": null,
  "createdAt": "2026-08-14T21:45:13Z",
  "channels": [
    {
      "channelId": "5b2e…",
      "channel": "Acme Inc",
      "platform": "linkedin",
      "status": "published",   // pending · publishing · published · failed
      "scheduledAt": null,
      "publishedAt": "2026-08-14T21:45:17Z",
      "url": "https://www.linkedin.com/feed/update/…",
      "externalPostId": "urn:li:share:…",
      "error": null            // short sanitized reason when a channel failed
    }
  ]
}

A practical polling loop after mode now: wait 10 to 15 seconds, fetch the post, and stop when its status is published, partial or failed. Image posts usually complete within seconds; video and Instagram carousels can take a minute or two.

Brandefer also runs a Model Context Protocol server for AI agents such as Claude, Claude Code and other MCP-capable clients. It uses the same API keys and capabilities and exposes a wider tool set: posting and per-channel rescheduling, media, per-post analytics, comment management and Instagram direct messages. Ready-made connect commands for Claude Code and Claude Desktop are shown next to every key you create, in the Agent access card of the project settings.