Check and schedule posts
POST /posts/validate checks a post against each account's platform rules and saves nothing; POST /posts and POST /posts/bulk run the same check, then schedule.
Every request that creates something takes an Idempotency-Key, and for 24 hours a retry with the same key gets the first answer instead of a second post.
Nothing posts right away: a post goes on your calendar at a time, at a best time or in the next free slot.
Save a draft
POST /drafts saves a post that goes nowhere until it's scheduled, with its text, accounts, a version per platform and pictures. PATCH /drafts/{id} changes it and DELETE /drafts/{id} deletes it. A draft shows under Your Buzz, where a teammate can finish it.
| Endpoint | Request | Needs |
|---|---|---|
| Create a draft | POST /api/v1/drafts | Draft |
| Update a draft | PATCH /api/v1/drafts/{id} | Draft |
| Delete a draft | DELETE /api/v1/drafts/{id} | Draft |
Check a post before it's scheduled
POST /posts/validate checks a post without saving anything: READY, WARNING or BLOCKED for each account, with the reason. It refuses what Buzzmark's composer refuses, such as a post over a platform's length, a missing picture, a TikTok post without its settings or a day that's full on an account. A warning goes out but shows differently, such as a post cut behind Show more.
POST /posts and POST /posts/bulk run the same check first. A post that would be BLOCKED answers 422 with the report, and nothing is saved.
Schedule
POST /posts schedules one post, a saved draft or one described in the request. POST /posts/bulk schedules up to 25 in one request, each checked on its own. A key needs the Schedule scope, and its maker must be an owner or an editor.
- A time with an offset, such as
2026-12-04T18:00:00+01:00, is that moment. A time without one is on the social set's clock. best_timepicks the soonest free hour when the accounts' posts do best, andnext_slottakes the set's next free posting slot.- A time must be at least 5 minutes out; nothing posts right away.
POST /posts/{id}/reschedule moves a scheduled post, /unschedule takes it back to the drafts, and /retry sends a failed post again to the accounts it failed on. GET /posts/{id} answers what happened on each account, with the live link and what the key can do to the post now.
| Endpoint | Request | Needs |
|---|---|---|
| Check a post without saving it | POST /api/v1/posts/validate | Read |
| Schedule a post | POST /api/v1/posts | Schedule |
| Schedule several posts | POST /api/v1/posts/bulk | Schedule |
| List posts | GET /api/v1/posts | Read |
| Get a post | GET /api/v1/posts/{id} | Read |
| Move a scheduled post | POST /api/v1/posts/{id}/reschedule | Schedule |
| Take a post off the schedule | POST /api/v1/posts/{id}/unschedule | Schedule |
| Send a failed post again | POST /api/v1/posts/{id}/retry | Schedule |
Retry without posting twice
Every POST that creates something takes an Idempotency-Key header: a value you make for that one request, such as a UUID. If the answer gets lost, send the same request with the same key. For 24 hours, Buzzmark answers what the first request did, with Idempotent-Replayed: true, and does nothing twice.
- The same key with another body is refused with
idempotency_mismatch. Make a new key for a new request. - While the first request still runs, the retry gets
in_flight: wait a moment and send it again. - When the first request failed on Buzzmark's side (a 5xx), the key is free again and the retry runs for real.
A request without the header answers 400 idempotency_key_required. Each endpoint that needs it says so on Endpoints.
Where to next
- Pictures and video
The Buzzmark API takes a picture or video 3 ways: an upload from your code, a copy from a public https link, or a picture Buzzmark's image model makes in your brand's colours.
- Webhooks
A Buzzmark webhook sends a signed POST to your server when a post is scheduled, goes out, fails or is approved, or when an account needs reconnecting.
- n8n and Make
n8n and Make call the Buzzmark API from n8n's HTTP Request node or Make's HTTP module, with your key in the Authorization header.
- Posting rules by platform
Each platform has its own rules for length, media, threads, mentions and first comments.