{
  "openapi": "3.1.0",
  "info": {
    "title": "Hanging Context public read API",
    "version": "1.0.0",
    "summary": "Free, keyless JSON, Markdown and feeds for Hanging Context stories.",
    "description": "Hanging Context publishes fresh context for agents. Stories are rebuilt every 12 hours. Each claim cites a Synorb Manifest. Every endpoint here is a read. No key is necessary. The same stories are also available through the MCP server at https://hangingcontext.com/mcp. Version policy: Breaking changes ship as a new version. We announce them at least 90 days ahead with Deprecation and Sunset response headers on the old version, and on the /developers page. Paging uses a cursor. Each REST list holds every story of its window, so the REST files have no cursor. To get only the stories that are new since your last call, call the MCP tool hc_since. It returns next_cursor and has_more, and you send next_cursor in your next call. Rate limit: 60 calls per 60 seconds per IP address for /ask and MCP tool calls.",
    "termsOfService": "https://hangingcontext.com/terms/reuse/",
    "contact": {
      "name": "Hanging Context",
      "email": "team@synorb.com",
      "url": "https://hangingcontext.com/contact/"
    },
    "license": {
      "name": "Hanging Context reuse terms",
      "url": "https://hangingcontext.com/terms/reuse/"
    },
    "x-api-version": "1",
    "x-sdks": [
      {
        "ecosystem": "npm",
        "language": "JavaScript",
        "package": "hanging-context",
        "version": "0.1.0",
        "url": "https://www.npmjs.com/package/hanging-context",
        "install": "npm install hanging-context",
        "cli": "hanging-context"
      },
      {
        "ecosystem": "pypi",
        "language": "Python",
        "package": "hanging-context",
        "version": "0.1.0",
        "url": "https://pypi.org/project/hanging-context/",
        "install": "pip install hanging-context",
        "cli": "hanging-context"
      }
    ],
    "x-pagination": {
      "style": "cursor",
      "tool": "hc_since",
      "cursor_field": "next_cursor",
      "more_field": "has_more",
      "note": "Paging uses a cursor. Each REST list holds every story of its window, so the REST files have no cursor. To get only the stories that are new since your last call, call the MCP tool hc_since. It returns next_cursor and has_more, and you send next_cursor in your next call."
    }
  },
  "servers": [
    {
      "url": "https://hangingcontext.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "stories",
      "description": "Stories and lists of stories."
    },
    {
      "name": "ask",
      "description": "Ask a question in plain words."
    },
    {
      "name": "feeds",
      "description": "Feeds for readers that poll."
    },
    {
      "name": "policy",
      "description": "Reuse terms."
    },
    {
      "name": "mcp",
      "description": "The MCP server."
    }
  ],
  "security": [],
  "paths": {
    "/editions/latest.json": {
      "get": {
        "operationId": "getLatestStories",
        "tags": [
          "stories"
        ],
        "summary": "Get the latest stories",
        "description": "Get the stories from the last 12 hours and the last 24 hours. The reply also lists the topics and the feed URLs.",
        "responses": {
          "200": {
            "description": "The latest stories.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LatestStories"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/n/{topic}/index.json": {
      "get": {
        "operationId": "getTopicStories",
        "tags": [
          "stories"
        ],
        "summary": "Get the stories of one topic",
        "description": "Get the recent stories of one topic, newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "name": "topic",
            "in": "path",
            "required": true,
            "description": "Topic slug. Get the slugs from the id of each topic in /editions/latest.json.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "example": "artificial-intelligence"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stories in the topic.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoryList"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/stories/{date}/{slug}/index.json": {
      "get": {
        "operationId": "getStory",
        "tags": [
          "stories"
        ],
        "summary": "Get one story as JSON",
        "description": "Get one story with its sections, key facts and cited Manifests.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Story date in UTC, as YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-10-15"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Story slug, from the url field of a story list.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{3,80}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The story.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Story"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/stories/{date}/{slug}/index.md": {
      "get": {
        "operationId": "getStoryMarkdown",
        "tags": [
          "stories"
        ],
        "summary": "Get one story as Markdown",
        "description": "Get one story as Markdown. Each paragraph cites Manifest ids.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Story date in UTC, as YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-10-15"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Story slug, from the url field of a story list.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{3,80}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The story as Markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/roundups/index.json": {
      "get": {
        "operationId": "listRoundups",
        "tags": [
          "stories"
        ],
        "summary": "List the roundups",
        "description": "List the recent roundups. A roundup groups related stories.",
        "responses": {
          "200": {
            "description": "The recent roundups.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoundupList"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/ask": {
      "get": {
        "operationId": "askQuestionGet",
        "tags": [
          "ask"
        ],
        "summary": "Ask a question (GET)",
        "description": "Answer a question from recent stories. The reply copies facts word for word. It uses no LLM. The protocol is NLWeb. Send Accept: text/event-stream or stream=true to stream.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "The question, in plain words. The name q is also accepted. Leave it out to get the help page.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "stream",
            "in": "query",
            "required": false,
            "description": "Set to true to get text/event-stream.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answer.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/AskAnswer"
                    },
                    {
                      "$ref": "#/components/schemas/AskHelp"
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "400": {
            "description": "The request is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "429": {
            "description": "Too many calls from this address. Wait, then call again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          },
          "500": {
            "description": "The server could not answer. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          }
        }
      },
      "post": {
        "operationId": "askQuestionPost",
        "tags": [
          "ask"
        ],
        "summary": "Ask a question (POST)",
        "description": "Answer a question from recent stories. The reply copies facts word for word. It uses no LLM. Set prefer.streaming to true to get text/event-stream.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AskAnswer"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "400": {
            "description": "The request is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "429": {
            "description": "Too many calls from this address. Wait, then call again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          },
          "500": {
            "description": "The server could not answer. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/editions/feed.json": {
      "get": {
        "operationId": "getJsonFeed",
        "tags": [
          "feeds"
        ],
        "summary": "Get the JSON Feed",
        "description": "Get all stories as a JSON Feed, newest first.",
        "responses": {
          "200": {
            "description": "A JSON Feed document.",
            "content": {
              "application/feed+json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonFeed"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/editions/feed.xml": {
      "get": {
        "operationId": "getRssFeed",
        "tags": [
          "feeds"
        ],
        "summary": "Get the RSS feed",
        "description": "Get all stories as an RSS feed, newest first.",
        "responses": {
          "200": {
            "description": "An RSS document.",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/editions/atom.xml": {
      "get": {
        "operationId": "getAtomFeed",
        "tags": [
          "feeds"
        ],
        "summary": "Get the Atom feed",
        "description": "Get all stories as an Atom feed, newest first.",
        "responses": {
          "200": {
            "description": "An Atom document.",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/.well-known/reuse.json": {
      "get": {
        "operationId": "getReuseTerms",
        "tags": [
          "policy"
        ],
        "summary": "Get the reuse terms",
        "description": "Get the reuse terms for stories in machine-readable form.",
        "responses": {
          "200": {
            "description": "The reuse terms.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReuseTerms"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              }
            }
          },
          "404": {
            "description": "No such file. The body is JSON, Markdown or HTML, chosen by the Accept header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpInfo",
        "tags": [
          "mcp"
        ],
        "summary": "Get the MCP connection details",
        "description": "A plain GET returns JSON that explains how to connect to the MCP server. A GET with Accept: text/event-stream and a session id opens the notification stream instead.",
        "responses": {
          "200": {
            "description": "How to connect.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpInfo"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      },
      "post": {
        "operationId": "callMcp",
        "tags": [
          "mcp"
        ],
        "summary": "Send an MCP JSON-RPC message",
        "description": "Send an MCP message over Streamable HTTP. Send initialize first. The tools are hc_ask, hc_latest, hc_since, hc_search, hc_get_story, hc_sources, hc_topics, hc_about.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The JSON-RPC response, as JSON or as text/event-stream.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            }
          },
          "400": {
            "description": "The request is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            }
          },
          "429": {
            "description": "Too many calls from this address. Wait, then call again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          },
          "500": {
            "description": "The server could not answer. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "HC-API-Version": {
                "$ref": "#/components/headers/HC-API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The JSON error body.",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A short error code.",
            "example": "empty_question"
          },
          "message": {
            "type": "string",
            "description": "What is wrong."
          },
          "next_step": {
            "type": "string",
            "description": "What to do next."
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds to wait. Only for code 429."
          }
        }
      },
      "StorySummary": {
        "type": "object",
        "description": "A story in a list.",
        "required": [
          "slug",
          "url",
          "headline",
          "published_at"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "json": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "format": "uri"
          },
          "headline": {
            "type": "string"
          },
          "dek": {
            "type": "string"
          },
          "beat": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "trust": {
            "type": "string"
          },
          "source_count": {
            "type": "integer"
          },
          "cited_manifest_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "StoryList": {
        "type": "object",
        "description": "A list of stories.",
        "required": [
          "stories"
        ],
        "properties": {
          "schema": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "story_count": {
            "type": "integer"
          },
          "stories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StorySummary"
            }
          }
        },
        "additionalProperties": true
      },
      "LatestStories": {
        "type": "object",
        "description": "The latest stories, the topics and the feeds.",
        "required": [
          "stories",
          "generated_at"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "stories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StorySummary"
            }
          },
          "published_last_24h": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StorySummary"
            }
          },
          "newsrooms": {
            "type": "array",
            "description": "The topics. Use id as the topic slug.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "json": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          },
          "feeds": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        "additionalProperties": true
      },
      "Story": {
        "type": "object",
        "description": "One story with the Manifests it cites.",
        "required": [
          "slug",
          "url",
          "headline",
          "published_at",
          "sections",
          "cited_manifest_ids"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "headline": {
            "type": "string"
          },
          "dek": {
            "type": "string"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "key_facts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                },
                "manifest_ids": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "additionalProperties": true
            }
          },
          "sections": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "unresolved": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cited_manifest_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "manifests": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "reuse": {
            "$ref": "#/components/schemas/ReuseTerms"
          }
        },
        "additionalProperties": true
      },
      "ReuseTerms": {
        "type": "object",
        "description": "The reuse terms for stories.",
        "properties": {
          "version": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "link_rule": {
            "type": "string"
          },
          "keep_ids_rule": {
            "type": "string"
          },
          "no_endorsement": {
            "type": "string"
          },
          "license_url": {
            "type": "string",
            "format": "uri"
          },
          "machine_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "AskRequest": {
        "type": "object",
        "description": "An NLWeb question.",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "The question."
          },
          "prefer": {
            "type": "object",
            "properties": {
              "streaming": {
                "type": "boolean",
                "description": "Set to true for text/event-stream."
              }
            }
          },
          "topic": {
            "type": "string",
            "description": "Only search this topic slug."
          },
          "days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "default": 7
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 5
          }
        }
      },
      "AskAnswer": {
        "type": "object",
        "description": "An NLWeb answer. Each result is a fact copied word for word from a story.",
        "required": [
          "_meta",
          "query",
          "results"
        ],
        "properties": {
          "_meta": {
            "type": "object",
            "required": [
              "response_type",
              "version"
            ],
            "properties": {
              "response_type": {
                "type": "string",
                "example": "answer"
              },
              "version": {
                "type": "string"
              },
              "protocol": {
                "type": "string"
              },
              "uses_llm": {
                "type": "boolean"
              }
            }
          },
          "query": {
            "type": "string"
          },
          "no_match": {
            "type": "boolean"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "datePublished": {
                  "type": "string"
                },
                "manifest_ids": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "additionalProperties": true
            }
          },
          "next_step": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "AskHelp": {
        "type": "object",
        "description": "How to call /ask. A GET with no question returns this.",
        "required": [
          "name",
          "methods",
          "parameters"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "protocol": {
            "type": "string"
          },
          "api_version": {
            "type": "string"
          },
          "methods": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "parameters": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "example": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "authentication": {
            "type": "object",
            "properties": {
              "required": {
                "type": "boolean"
              }
            }
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "window_seconds": {
                "type": "integer"
              },
              "scope": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      },
      "McpInfo": {
        "type": "object",
        "description": "How to connect to the MCP server. A plain GET to /mcp returns this.",
        "required": [
          "name",
          "endpoint",
          "transport",
          "tools"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "com.hangingcontext/mcp"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "endpoint": {
            "type": "string",
            "format": "uri"
          },
          "transport": {
            "type": "string",
            "example": "streamable-http"
          },
          "authentication": {
            "type": "object",
            "properties": {
              "required": {
                "type": "boolean"
              }
            }
          },
          "how_to_connect": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "server_card": {
            "type": "string",
            "format": "uri"
          },
          "api_version": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "JsonRpcRequest": {
        "type": "object",
        "description": "A JSON-RPC 2.0 request for the MCP server.",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "type": [
              "string",
              "integer"
            ]
          },
          "method": {
            "type": "string",
            "example": "initialize"
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "description": "A JSON-RPC 2.0 response from the MCP server.",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "RoundupList": {
        "type": "object",
        "description": "The recent roundups. A roundup groups related stories.",
        "required": [
          "roundups"
        ],
        "properties": {
          "schema": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "roundups": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "title",
                "url",
                "scope",
                "published_at"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "dek": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "json": {
                  "type": "string",
                  "format": "uri"
                },
                "scope": {
                  "type": "object",
                  "description": "What the roundup covers. The type is topic, beat or topics.",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                },
                "edition": {
                  "type": "string"
                },
                "published_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "story_count": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "JsonFeed": {
        "type": "object",
        "description": "A JSON Feed 1.1 document.",
        "required": [
          "version",
          "title",
          "items"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "home_page_url": {
            "type": "string",
            "format": "uri"
          },
          "feed_url": {
            "type": "string",
            "format": "uri"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "title": {
                  "type": "string"
                },
                "date_published": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    },
    "parameters": {
      "ApiVersion": {
        "name": "HC-API-Version",
        "in": "header",
        "required": false,
        "description": "The API version you expect. Version 1 is the only version today. Every response carries the HC-API-Version header.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ],
          "default": "1"
        }
      }
    },
    "headers": {
      "HC-API-Version": {
        "description": "The API version of this response.",
        "schema": {
          "type": "string",
          "example": "1"
        }
      },
      "RateLimit-Policy": {
        "description": "The limit policy, for example \"hc-public\";q=60;w=60 (60 calls per 60 seconds).",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit": {
        "description": "The calls left and the seconds until reset, for example \"hc-public\";r=59;t=60.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Limit": {
        "description": "Calls allowed in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Calls left in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before you call again.",
        "schema": {
          "type": "integer"
        }
      }
    }
  },
  "externalDocs": {
    "description": "Hanging Context developers: the MCP server, the SDKs and the CLI, rate limits and errors.",
    "url": "https://hangingcontext.com/developers/"
  }
}
