# pickthepost for AI agents

pickthepost publishes to Instagram, Facebook Pages, Threads and Bluesky through official APIs. Agents prepare posts
through pickthepost's API; people decide what goes out. Access is by an API key issued to the account owner during
early access. Never ask a person for a social network password: pickthepost never needs one.

## The rule
Create posts as drafts (`"draft": true`). A draft never goes out by itself. A person schedules it in the app.

## Endpoints (base: https://api.pickthepost.com, header `Authorization: Bearer <key>`)
- `PUT /admin/media?name=FILE&w=W&h=H&dur=SECONDS` with the file as the body: stores a photo or video, returns `{key, url}`.
- `POST /admin/posts` with a post (below): creates it, returns `{id, at, status}`. Checks every caption against each platform's limit and refuses what would be refused.
- `PATCH /admin/posts/ID` with any of `at, caption, media, targets, key`: changes a draft or a scheduled post.
- `GET /admin/posts?from=ISO&to=ISO&status=draft,scheduled`: lists posts with each platform's status, result link and stats.
- `GET /admin/queue/next`: the next free posting slot.

## A post
```json
{
  "key": "carousel_rome",
  "at": "2026-10-21T07:00:00Z",
  "draft": true,
  "caption": "Where to stay in Rome, near the Trevi Fountain: 5 real picks…",
  "media": {"kind": "images", "items": [{"key": "m/…/slide_0.jpg", "width": 1080, "height": 1350}]},
  "targets": [
    {"platform": "instagram", "account": "instagram_youraccount", "first_comment": "Which city next?"},
    {"platform": "threads", "account": "threads_youraccount", "caption": "A version within 500 characters"},
    {"platform": "bluesky", "account": "bluesky_youraccount", "caption": "A version within 300 characters"}
  ]
}
```

## Limits to respect
Instagram 2,200 characters and 30 hashtags, JPEG photos only, up to 10 per carousel; Threads 500 characters; Bluesky
300 characters and the first 4 photos; one video per post. Full numbers: https://pickthepost.com/guides