PostsEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/findlocal/main/json-schema/findlocal-posts-envelope-schema.json",
  "title": "PostsEnvelope",
  "description": "Same envelope as every other route. `data.items` carries the posts the account itself wrote — reposts and boosts of other people are excluded by authorship. `has_more` is false and `next_cursor` is null on all three platforms today: there is no deep pagination, and the fields are present so the shape does not change on the day there is.",
  "x-generated": "2026-09-25",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/findlocal-openapi.json#/components/schemas/PostsEnvelope",
  "type": "object",
  "required": [
    "success",
    "platform",
    "endpoint",
    "data",
    "error",
    "credits_used",
    "cached",
    "request_id"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "platform": {
      "type": "string"
    },
    "endpoint": {
      "type": "string"
    },
    "data": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "author": {
          "$ref": "#/$defs/Author"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PostItem"
          }
        },
        "has_more": {
          "type": "boolean"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "error": {
      "type": [
        "object",
        "null"
      ]
    },
    "credits_used": {
      "type": "integer"
    },
    "cached": {
      "type": "boolean"
    },
    "request_id": {
      "type": "string"
    }
  },
  "$defs": {
    "Author": {
      "type": "object",
      "description": "The same twelve names on every platform. A field that does not exist there is null, never absent and never zero: zero is a fact about the account, null is a fact about our reading.",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Stable identifier on that platform."
        },
        "handle": {
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "bio": {
          "type": [
            "string",
            "null"
          ]
        },
        "avatar_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "followers": {
          "type": [
            "integer",
            "null"
          ]
        },
        "following": {
          "type": [
            "integer",
            "null"
          ]
        },
        "posts_count": {
          "type": [
            "integer",
            "null"
          ]
        },
        "verified": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "is_private": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "external_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "PostItem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        },
        "text": {
          "type": [
            "string",
            "null"
          ]
        },
        "text_html": {
          "type": [
            "string",
            "null"
          ],
          "description": "Mastodon only. Third-party HTML, unsanitised — sanitise before rendering or you have an XSS hole. `text` is the same content already stripped."
        },
        "title": {
          "type": "null",
          "description": "Always null: a status has no title."
        },
        "position": {
          "type": "null",
          "description": "Always null: chronological order is not a ranking."
        },
        "published_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "thumbnail_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Null on bluesky and mastodon — the image embed has not been measured on a large enough sample to promise a shape."
        },
        "metrics": {
          "type": "object",
          "properties": {
            "likes": {
              "type": [
                "integer",
                "null"
              ]
            },
            "replies": {
              "type": [
                "integer",
                "null"
              ]
            },
            "reposts": {
              "type": [
                "integer",
                "null"
              ]
            },
            "quotes": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Null on threads: the source publishes none."
            }
          }
        }
      }
    }
  }
}