ChatGptResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/irmu-com/json-schema/irmu-com-chat-gpt-result-schema.json",
  "title": "ChatGptResult",
  "description": "What `/chatgpt` answers. `conversation` is empty while a prompt is still\nrunning and when it went unanswered; `status` and `error` are what tell\nthose two apart.\n",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/irmu-com-openapi.yaml#/components/schemas/ChatGptResult",
  "type": "object",
  "required": [
    "prompt",
    "conversation",
    "credits_charged",
    "credits_remaining",
    "job_id",
    "status",
    "debug"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The question, as it was asked."
    },
    "conversation": {
      "type": "array",
      "description": "The exchange. The user turn carries `message`; the assistant turn\ncarries `response`, a list of nodes.\n",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "message": {
            "type": "string",
            "description": "The prompt. Present on the user turn only."
          },
          "response": {
            "type": "array",
            "description": "The answer, node by node. `type` says which shape each one is:\n`paragraph` and `heading` carry `text` (and `heading` a `level`),\n`bullet_list` and `ordered_list` carry `items`, `table` carries\n`headers` and `rows`, `product_list` carries `items`, and\n`divider` carries nothing. Any node may carry `sources`, the\ncitations ChatGPT showed beside it.\n",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    },
    "credits_charged": {
      "type": "integer",
      "description": "30 for a prompt that was answered or is still running, 0 for one that\nwas not.\n"
    },
    "credits_remaining": {
      "type": "integer"
    },
    "job_id": {
      "type": "string",
      "description": "What this ran under. Collect a `202` from `/crawl/{job}` with it.\n"
    },
    "status": {
      "type": "string",
      "enum": [
        "done",
        "queued",
        "running",
        "failed"
      ]
    },
    "position": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Where it sits in the crawler's queue while `queued`."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why nothing came back. Null otherwise."
    },
    "debug": {
      "description": "Where the crawl had got to, when the crawler stopped waiting and\nlooked. Only sent when the request carries `debuga=1` -- a screenshot\nand the page source run to a megabyte -- and null otherwise.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/CrawlSnapshot"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$defs": {
    "CrawlSnapshot": {
      "type": "object",
      "description": "Where a crawl had got to, for one that is still running or failed. Only\nsent when the request carries `debuga=1`.\n\nThe crawler stops waiting long before it stops working, and when it stops\nwaiting it looks at the tab: the url the browser is on, a picture of what\nis on screen, and the page source as it stands. That is what this is --\na diagnosis for a request that timed out, not a result. Nothing is\ncharged for it.\n\nNull on anything that is not still running. A finished or failed crawl has\nno tab left to look at, and a crawl still in the queue has not opened one\nyet.\n\nTwo things to know when reading one. The image is the **viewport**, not\nthe whole page, so it is not the picture `/screenshot` sells -- it is a\nthumbnail at quality 60, meant to be looked at rather than kept. And\neither artefact may be missing: they are captured independently, because a\nnavigation can destroy one without touching the other, so half a snapshot\nis ordinary. The missing half reads as null rather than going absent.\n\nA blank image beside a near-empty `html` is not a broken capture -- it\nmeans the crawl stalled *inside* a navigation, with the old document\nalready replaced. That is itself the answer.\n",
      "required": [
        "url",
        "screenshot",
        "html"
      ],
      "properties": {
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "The url the tab was on, which a redirect may have moved away from the\none you asked for.\n"
        },
        "screenshot": {
          "type": [
            "string",
            "null"
          ],
          "format": "byte",
          "description": "A base64 JPEG of the viewport, with no `data:` prefix -- decode it as\nit stands. Null when the capture raced a navigation and lost.\n"
        },
        "html": {
          "type": [
            "string",
            "null"
          ],
          "description": "The page source at that moment, half-loaded and all. Null when the\ncapture raced a navigation and lost.\n"
        }
      }
    }
  }
}