Why publishing is async
Posting to a social platform can take seconds (video processing, retries on
transient failures). So POST /v1/publish does not wait. It validates your
request, enqueues a job, and returns 202 Accepted with a job_id. Delivery
happens in the background and the result is recorded per account.
The job lifecycle
POST /v1/publish
|
v
[queued] --> [processing] --> [published] (all accounts ok)
\--> [partial] (some ok, some failed)
\--> [failed] (none ok)
scheduled_at set:
[scheduled] --(time arrives)--> [queued] --> ...
A job fans out to every account in account_ids. Each account gets its own
delivery result with the platform post id or a structured error.
Statuses
| Status | Meaning |
|---|---|
scheduled | Accepted for a future time, not yet queued. |
queued | In the delivery queue, waiting for a worker. |
processing | Being delivered to the target platforms. |
published | Delivered to every targeted account. |
partial | Delivered to some accounts; others failed. |
failed | Failed for every account. |
canceled | A scheduled job was canceled before it queued. |
Read the per account results in the publish history to see which account produced which outcome.
Scheduling
Pass scheduled_at as an ISO 8601 timestamp with a timezone offset. It must be
at least 60 seconds in the future. The job sits in scheduled until its time
arrives, then moves to queued. You can cancel it while it is still scheduled
with POST /v1/publish/{job_id}/cancel. See the
scheduling guide.
Idempotency
Network retries can cause you to send the same request twice. Send an
Idempotency-Key header with a unique value per logical post and Dravo returns
the original job for repeated calls instead of enqueuing a duplicate.
curl -X POST https://api.dravo.dev/v1/publish \
-H "Authorization: Bearer $DRAVO_API_KEY" \
-H "Idempotency-Key: post-2026-06-23-launch" \
-H "Content-Type: application/json" \
-d '{ "account_ids": ["acc_8f2c1d"], "text": "Launch day." }'