Response format

The PostOnce Public API uses a consistent response envelope across resources.

Success responses

Successful responses return a data object:

{
  "data": {
    "id": "post_123",
    "status": "scheduled"
  }
}

List responses may also include meta:

{
  "data": [],
  "meta": {
    "next_cursor": null
  }
}

Errors return an error object:

{
  "error": {
    "code": "missing_scope",
    "message": "Missing required scope: posts:write"
  }
}

Some errors include details:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": {
      "field": "publish_at"
    }
  }
}

Use Idempotency-Key on POST /v1/posts when retrying create requests.

This lets clients retry safely without creating duplicate post jobs.