Skip to content
HeadlessWP Pro

API schema appendix

Shared envelope, metadata, and cross-endpoint patterns.

API schema appendix

This appendix describes shared response conventions used across HeadlessWP Pro routes consumed by this site.

Shared envelope shape

Most responses follow a common envelope with top-level data, meta, and (when applicable) error.

{
  "data": {},
  "meta": {
    "correlationId": "...",
    "correlation_id": "..."
  },
  "error": null
}

Notes:

  • data carries the endpoint payload for successful operations.
  • meta carries cross-cutting metadata (including correlation identifiers).
  • error carries structured failure details when the request is unsuccessful.

Correlation id fields

For compatibility across clients and upstream systems, responses may include both:

  • meta.correlationId
  • meta.correlation_id

Treat these as equivalent references to the same request trace id.

Common pagination patterns

When list endpoints are paginated, this repo commonly uses cursor-style metadata where applicable:

  • request includes cursor-compatible paging inputs
  • response metadata includes a nextCursor value when a subsequent page exists
  • clients continue until nextCursor is absent/null

Some routes may also expose route-specific pagination metadata; follow each endpoint contract page before implementing client assumptions.

Endpoint-specific schemas

Use /docs/api/endpoints for endpoint-level request and response schemas, auth expectations, and route-specific rules.