{
  "openapi": "3.0.3",
  "info": {
    "title": "Hacker News Chinese Edition API",
    "version": "1.0.0",
    "description": "A read-only REST API served by a single Cloudflare Worker. It proxies the official Hacker News (Firebase) API and the Algolia HN Search API, and optionally translates story titles and comments into Simplified Chinese with Cloudflare Workers AI (@cf/meta/m2m100-1.2b).",
    "contact": {
      "name": "Source",
      "url": "https://github.com/HackerNews/API"
    }
  },
  "servers": [
    {
      "url": "https://ycnews.331319.xyz",
      "description": "Cloudflare Worker edge"
    }
  ],
  "tags": [
    {
      "name": "Stories",
      "description": "Front page / newest / best / ask / show / jobs feeds"
    },
    {
      "name": "Item",
      "description": "Single story and its comment tree"
    },
    {
      "name": "Search",
      "description": "Full-text search powered by Algolia"
    },
    {
      "name": "Utility",
      "description": "Translation, health, feed catalogue"
    }
  ],
  "paths": {
    "/api/v1/stories": {
      "get": {
        "tags": [
          "Stories"
        ],
        "summary": "List stories",
        "description": "Returns a paginated list of stories for the requested feed. Titles are translated to Simplified Chinese when translate=1.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "top",
              "enum": [
                "top",
                "new",
                "best",
                "ask",
                "show",
                "job"
              ]
            },
            "description": "Feed id: top, new, best, ask, show, job"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Page number (1-based)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Items per page"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Optional keyword filter (Algolia feeds only)"
          },
          {
            "name": "translate",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "1 = Chinese titles, 0 = original English"
          },
          {
            "name": "pretty",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Pretty-printed JSON envelope"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "ok": true,
                  "meta": {
                    "type": "top"
                  },
                  "data": {
                    "count": 20,
                    "items": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid type parameter"
          }
        }
      }
    },
    "/api/v1/story/{id}": {
      "get": {
        "tags": [
          "Item"
        ],
        "summary": "Get one story",
        "description": "Story detail from the official HN API. Add comments=1 to embed the comment tree.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Hacker News item id, e.g. 8863"
          },
          {
            "name": "comments",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "1 = include comment tree"
          },
          {
            "name": "depth",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2,
              "minimum": 1,
              "maximum": 4
            },
            "description": "Comment tree depth"
          },
          {
            "name": "max_comments",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 60,
              "maximum": 200
            },
            "description": "Max comments to fetch per request"
          },
          {
            "name": "translate",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Translate title/text"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Story not found"
          }
        }
      }
    },
    "/api/v1/comments/{id}": {
      "get": {
        "tags": [
          "Item"
        ],
        "summary": "Comment tree",
        "description": "Returns the nested comment tree of a story, translated when translate=1.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2,
              "minimum": 1,
              "maximum": 4
            }
          },
          {
            "name": "max",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 60,
              "maximum": 200
            }
          },
          {
            "name": "translate",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Search stories",
        "description": "Full-text search over HN stories via the Algolia HN Search API.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword, e.g. cloudflare"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          },
          {
            "name": "translate",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Missing q"
          }
        }
      }
    },
    "/api/v1/translate": {
      "get": {
        "tags": [
          "Utility"
        ],
        "summary": "Translate a string",
        "description": "Translate arbitrary English text to Simplified Chinese (or any m2m100 target code such as fr, de, ja).",
        "parameters": [
          {
            "name": "text",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Text to translate (max 900 chars)"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "zh"
            },
            "description": "Target language code"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Missing text"
          }
        }
      }
    },
    "/api/v1/feeds": {
      "get": {
        "tags": [
          "Utility"
        ],
        "summary": "Available feeds",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "tags": [
          "Utility"
        ],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}