Skip to the page

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.

EndpointRequestNeeds
Create a draftPOST /api/v1/draftsDraft
Update a draftPATCH /api/v1/drafts/{id}Draft
Delete a draftDELETE /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_time picks the soonest free hour when the accounts' posts do best, and next_slot takes 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.

EndpointRequestNeeds
Check a post without saving itPOST /api/v1/posts/validateRead
Schedule a postPOST /api/v1/postsSchedule
Schedule several postsPOST /api/v1/posts/bulkSchedule
List postsGET /api/v1/postsRead
Get a postGET /api/v1/posts/{id}Read
Move a scheduled postPOST /api/v1/posts/{id}/rescheduleSchedule
Take a post off the schedulePOST /api/v1/posts/{id}/unscheduleSchedule
Send a failed post againPOST /api/v1/posts/{id}/retrySchedule

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