Getting started
Errors & responses
Responses are boringly consistent. Success returns data; failure returns an error string and a matching HTTP status. No envelopes to unwrap, no error codes to memorize.
The response envelope
- A single resource is returned directly — the object sits at the top level of the response.
- A collection is wrapped:
{ "data": [ … ] }. - An error is always
{ "error": "message" }with a non-2xx status.
// Error shape — same for every failure
{
"error": "Post not found."
}Status codes
| Code | Meaning | When |
|---|---|---|
| 200 | OK | A successful read, or a delete. |
| 201 | Created | A post was created (published or scheduled). |
| 400 | Bad Request | Validation failed — see the error message. |
| 401 | Unauthorized | Missing, malformed, or revoked API key. |
| 404 | Not Found | No such post belongs to your account. |
| 500 | Server Error | Something broke on our side. Retry shortly. |
Common errors
| Status | Message | Fix |
|---|---|---|
| 401 | Missing API key. Send `Authorization: Bearer pmi_live_…`. | Add the Authorization header. |
| 401 | Invalid or revoked API key. | Use a current, un-revoked key. |
| 400 | Select at least one connected network. | Target a network from /accounts. |
| 400 | Add a caption or media before publishing. | Provide caption text, media, or both. |
| 400 | `schedule_at` must be a unix timestamp or ISO 8601 date. | Send seconds, milliseconds, or ISO 8601. |
| 400 | `schedule_at` must be a time in the future. | Use a future time (60s skew allowed). |
| 404 | Post not found. | Check the post id belongs to you. |
Partial publishes
A single post fans out to many networks, and they don’t all succeed or fail together. If one network rejects the post while others accept it, the post still moves to published — the status reflects that the fan-out ran, not that every network delivered.
Per-network delivery outcomes are captured internally and shown in the dashboard. The public API currently returns the aggregate status and metrics; a per-network delivery breakdown over the API is on the roadmap. Until then, treat reach and engagement_rate as reported figures that start at 0 and grow as networks report back — see Post lifecycle.
No idempotency keys (yet)
POST /posts publishes again — there’s no automatic de-duplication. Guard against accidental double-sends on your side, and see Handle partial failures for a safe retry pattern.