Envelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/helious-io/json-schema/helious-io-envelope-schema.json",
  "title": "Envelope",
  "description": "Every /v1 response. `summary` states the answer as one plain-English sentence and `source` says who to credit for it, both before the raw `data`, so the finished claim is the first thing a reader meets.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/helious-io-openapi.json#/components/schemas/Envelope",
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns."
    },
    "source": {
      "type": "object",
      "description": "Who to credit and where a reader can check the number.",
      "properties": {
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The Helious page backing this answer."
        },
        "cite_as": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "live": {
          "type": "string",
          "description": "How current these numbers are on YOUR plan, and how to ask for them again. Says the data is live only on a tier that serves it live."
        }
      }
    },
    "data": {
      "type": "object",
      "description": "The dataset itself."
    },
    "meta": {
      "type": "object",
      "description": "When it was true, and what your plan allows."
    },
    "plan_limit": {
      "type": "object",
      "description": "Present only when your plan moved the window AND Helious holds rows older than it. Says this is a plan limit rather than missing data, where the record begins (record_begins, on the lanes that say it), the plans that reach further, and the exact step to relay to the person you work for."
    },
    "record_start": {
      "type": "object",
      "description": "Present instead of plan_limit when you asked for more history than any plan reads here: record_begins is the first day any plan reads (null when there is none yet), your plan's window already reaches it, older_rows_on_any_plan is false, and meta.clamped is false. No plan reaches further back, so there is nothing to upgrade for."
    }
  }
}