> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postonce.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Response format

> Understand the standard success and error envelopes used by the PostOnce Public API.

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

## Success responses

Successful responses return a `data` object:

```json theme={null}
{
  "data": {
    "id": "post_123",
    "status": "scheduled"
  }
}
```

List responses may also include `meta`:

```json theme={null}
{
  "data": [],
  "meta": {
    "next_cursor": null
  }
}
```

## Error responses

Errors return an `error` object:

```json theme={null}
{
  "error": {
    "code": "missing_scope",
    "message": "Missing required scope: posts:write"
  }
}
```

Some errors include `details`:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": {
      "field": "publish_at"
    }
  }
}
```

## Idempotency

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

* Same key + same request body returns the stored result
* Same key + different request body returns `409`

This lets clients retry safely without creating duplicate post jobs.