Postbito API

Quick start

1. 1. In Postbito, open API & agents and create a key with the permissions it needs.
2. 2. Send it as a Bearer token:

curl https://postbito.com/api/v1/channels \
  -H "Authorization: Bearer pbt_your_key" \
  -H "Accept: application/json"

3. 3. Draft a post for two channels, with its own caption on one of them, and send it for approval:

curl -X POST https://postbito.com/api/v1/posts \
  -H "Authorization: Bearer pbt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Doors at 9 tonight", "channels": [3],
       "targets": [{"channel_id": 4, "text": "Doors at 9 🎶 see you there"}],
       "action": "submit"}'

The pipeline

Postbito is built to sit in the middle of an agent-made content loop. Each step has an endpoint and an MCP tool; the one step without either — approving — is a person’s.

1. Step 01

   Request

   People (or agents) file ideas: a topic, the channels it’s for, the day it goes out.

   GET /ideas · PATCH /ideas/{id}
   list_ideas · update_idea

2. Step 02

   Build

   Your agent writes the captions and makes the photos and videos — a cut per network where it helps.

   Your tools
   Your tools

3. Step 03

   Check

   Every caption and file is checked against each network’s rules before anything is saved.

   POST /posts/validate
   check_post

4. Step 04

   Upload

   Hand over finished files — uploaded, or by a public link Postbito fetches.

   POST /media
   upload_media_from_url

5. Step 05

   Draft

   One post, a caption (and media, and options) per channel where they differ.

   POST /posts
   create_post

6. Step 06

   Approve

   A person watches every post in Postbito and signs it off — or sends it back with a note.

   GET /posts?status=changes_requested
   list_posts · update_post · submit_post

7. Step 07

   Publish

   Postbito posts each channel’s copy on schedule and records the link.

   GET /posts/{id}
   get_post

8. Step 08

   Clean up

   Files are deleted once every post using them is live.

   GET /media/{id}
   —

9. Step 09

   Learn

   Weekly results — against the week before, by channel, best posts and hours — shape the next ideas.

   GET /analytics
   get_analytics

When a reviewer sends a post back it becomes changes_requested with their review_note — back to Build. Fix it, PATCH it, and submit it again.

Keys & permissions

Keys belong to the team, not a person, so integrations keep working when people come and go. Owners and admins create them; a key is shown once. Each has up to four permissions:

MCP server

Postbito runs a Streamable HTTP MCP server at https://postbito.com/mcp. It takes the same keys and permissions — tools a key can’t use are hidden — and its instructions teach the pipeline above.

Claude Code

claude mcp add --transport http postbito https://postbito.com/mcp \
  --header "Authorization: Bearer pbt_your_key"

Claude Desktop, Cursor, VS Code and other clients

{
    "mcpServers": {
        "postbito": {
            "type": "http",
            "url": "https://postbito.com/mcp",
            "headers": {
                "Authorization": "Bearer pbt_your_key"
            }
        }
    }
}

Conventions

• Write once, per channel where it differs. A post has a caption ("text") and media every channel gets. targets[] gives one channel its own caption, media (a vertical cut for TikTok, say) or network options. A target’s text or media left out (or null, or []) uses the post’s. Shorthand: a channels entry can be an object too — {"id": 4, "text": "…"}.
• Actions — draft (the default) keeps it to finish later; submit asks for approval; queue puts each channel’s copy in its next free posting-schedule slot; schedule sends it at scheduled_at; now sends it right away. With submit, scheduled_at or publish_mode (queue, now, at) says what happens once it’s approved.
• PATCH changes only what you send. targets edits channels one at a time; channels replaces the list. Without an action a post keeps its state — a draft stays a draft, a scheduled post stays scheduled.
• Statuses — post: draft, pending_approval, changes_requested, scheduled, published, partial, failed. Each channel (target): draft, scheduled, publishing, published, failed.
• next on every post says, in a sentence, what happens now and what you can do about it.
• Media is cleaned up. Once every post using a file is live, the file is deleted (its record and thumbnail stay; url becomes null). Turn it off per file with purge_after_publish, or for the team in Publishing settings.
• Times are ISO 8601; send an offset (2026-11-02T09:00:00-05:00) or Z. Dates (publish_on, analytics from/to) are YYYY-MM-DD in the team’s time zone.
• Responses wrap resources in "data"; lists add "links" and "meta" for paging (per_page up to 100). Each post has a url that opens it in Postbito.

Endpoints

Base URL: https://postbito.com/api/v1 · PUT works wherever PATCH does.

Account

Channels

Ideas

{
    "title": "Halloween weekend on the rooftop",
    "body": "Costume contest Saturday, 2-for-1 cocktails.",
    "channel_ids": [
        3,
        4,
        7
    ],
    "publish_on": "2026-10-30"
}

{
    "status": "in_progress"
}

Media

{
    "url": "https://bucket.example.com/videos/halloween-vertical.mp4",
    "alt_text": "Costumes on the rooftop",
    "purge_after_publish": true
}

{
    "purge_after_publish": false
}

Posts

{
    "text": "Costume contest Saturday at 10pm 🎃",
    "media": [
        41
    ],
    "channels": [
        3,
        4
    ]
}

{
    "text": "Costume contest Saturday at 10pm 🎃",
    "media": [
        41
    ],
    "channels": [
        3
    ],
    "targets": [
        {
            "channel_id": 4,
            "text": "Costume contest Sat 10pm. 2-for-1 if you dress up 🎃"
        },
        {
            "channel_id": 7,
            "media": [
                42
            ],
            "options": {
                "privacy_level": "PUBLIC_TO_EVERYONE"
            }
        }
    ],
    "idea_id": 12,
    "action": "submit"
}

{
    "targets": [
        {
            "channel_id": 7,
            "media": [
                43
            ]
        }
    ]
}

Analytics

The post object

What POST /posts takes:

{
    "text": "Costume contest Saturday at 10pm 🎃",
    "media": [
        41
    ],
    "channels": [
        3
    ],
    "targets": [
        {
            "channel_id": 4,
            "text": "Costume contest Sat 10pm. 2-for-1 if you dress up 🎃"
        },
        {
            "channel_id": 7,
            "media": [
                42
            ],
            "options": {
                "privacy_level": "PUBLIC_TO_EVERYONE"
            }
        }
    ],
    "idea_id": 12,
    "action": "submit"
}

And what comes back (shortened):

{
  "data": {
    "id": 88,
    "status": "changes_requested",
    "text": "Costume contest Saturday at 10pm 🎃",
    "media": [{ "id": 41, "kind": "video", "mime_type": "video/mp4", "duration": 24.5, "url": "https://postbito.com/media/9f1c…/halloween.mp4?signature=…", "purged_at": null }],
    "targets": [
      {
        "id": 210,
        "channel": { "id": 4, "network": "x", "name": "Harbor House", "handle": "@harborhouse" },
        "status": "draft",
        "text": "Costume contest Sat 10pm. 2-for-1 if you dress up 🎃",
        "own_text": true,
        "media": [],
        "options": {},
        "scheduled_at": null,
        "published_at": null,
        "remote_url": null,
        "error": null,
        "metrics": {}
      }
    ],
    "publish_mode": "queue",
    "idea_id": 12,
    "author": "Claude Code",
    "created_via": "api",
    "review_note": "Say the contest starts at 10pm sharp, and use the vertical cut on X too.",
    "reviewed_by": "Chris",
    "next": "A reviewer asked for changes: \"Say the contest starts at 10pm sharp…\". Rebuild what they asked for, update the post (PATCH /api/v1/posts/{id}, MCP: update_post) and submit it again.",
    "url": "https://postbito.com/your-team/posts/88/edit"
  }
}

Network rules

What each network takes. POST /posts/validate checks all of it; GET /channels returns it per channel as "rules". X counts every link as 23 characters and emoji as 2.

Network options targets[].options

Errors & limits

{
  "message": "X allows 280 characters; this is 312 (32 over). (and 1 more error)",
  "errors": {
    "targets.4": ["X allows 280 characters; this is 312 (32 over)."],
    "targets.7": ["Instagram needs a photo or a video."]
  }
}

Uploads can be up to 250 MB. The Free plan holds 10 scheduled posts per channel; Essentials and Team are unlimited.