Getting started

Response envelope

Every successful response uses the same shape: { "data": ..., "meta": { ... } }. The data field carries the resource; meta carries request-tracing and pagination state.

Meta fields

meta.request_id	string	UUID for the request. Include it in any support inquiry.
meta.page.next_cursor	string \| null	Opaque token for the next page, or null if no more.
meta.page.prev_cursor	string \| null	Opaque token for the previous page (where supported).
meta.cache_ttl_seconds	integer	Server-side cache age for this resource. Use it to time your client cache.

Example: subreddit metadata

A successful GET /v1/subreddits/python looks like:

{
  "data": {
    "id": "2qh0y",
    "fullname": "t5_2qh0y",
    "display_name": "Python",
    "name_prefixed": "r/Python",
    "title": "Python",
    "public_description": "The largest Python community for Reddit! Stay up to date with the latest news, packages, and meta information relating to the Python programming language. 
---

If you have questions or are new to Python use r/LearnPython",
    "description": "####[The Python Discord](https://discord.gg/python)

News about the dynamic, interpreted, interactive, object-oriented, extensible programming language Python

# Upcoming Events
[Full Events Calendar](https://www.python.org/events/) 

# Ple…" /* 5689 more chars */,
    "description_html": "<!-- SC_OFF --><div class="md"><h4><a href="https://discord.gg/python">The Python Discord</a></h4>

<p>News about the dynamic, interpreted, interactive, object-oriented, extensible programming language Python</p>

<h1>Upcoming Events</h1>

…" /* 7850 more chars */,
    "subreddit_type": "public",
    "subscribers": 1479142,
    "active_user_count": null,
    "created_utc": "2008-01-25T03:14:39+00:00",
    "over_18": false,
    "lang": "en",
    "icon_img": null,
    "banner_img": null,
    "header_img": "https://b.thumbs.redditmedia.com/8HiO52_EuT_h63Qg.png",
    "url": "/r/Python/"
  },
  "meta": {
    "request_id": "<redacted>"
  }
}

Bypass routes

Two routes deliberately skip the envelope so cluster orchestrators and metrics tools can read them with no parsing:

/v1/healthzReturns raw {"status":"ok"} — what Kubernetes / ALB liveness probes expect.
/metricsReturns Prometheus text format (when enabled with a scrape token).

Example:

{
  "status": "ok"
}

← Previous

Authentication

Pagination