{"openapi":"3.1.0","info":{"title":"Hacker News (Firebase) API","description":"Official Hacker News public API served from Firebase Realtime Database. This specification documents the official v0 endpoints hosted at https://hacker-news.firebaseio.com (no trailing slash) as described by the provider. Authentication: none — the API is public and read-only. Rate limits: none are formally published; the provider asks clients to be considerate (cache results, avoid tight polling, and back off on errors). Data model: items (stories, comments, jobs, polls, poll options) and users. Common fields: time is a Unix timestamp (seconds since epoch). Lists (top/new/best/ask/show/job) return arrays of item IDs (up to ~500 for top/new/best and ~200 for ask/show/job at any moment). Pretty-printing: pass print=pretty to any .json endpoint for human-readable formatting. Streaming: Firebase REST supports Server-Sent Events (SSE). You can subscribe to changes at any endpoint by setting the Accept header to text/event-stream on the same URL (ending in .json). The stream emits event: put/patch/keep-alive with JSON payloads. Note: SSE is best-effort and subject to underlying Firebase behavior (timeouts, reconnects). Pagination: not applicable — list endpoints return fixed-length ID arrays reflecting the current state. Caching: responses may be cached by clients; item IDs are immutable once created, while item and user fields can change (e.g., score, descendants, kids). Error handling: the service may return generic HTTP errors (400 for malformed input, 404 for nonexistent resources, 429/5xx under load). Contact: api@ycombinator.com.","version":"v0"},"servers":[{"url":"https://api.onestop.sh/v1/invoke/one-stop/hacker-news-api"}],"security":[{"oneStopApiKey":[]}],"components":{"securitySchemes":{"oneStopApiKey":{"type":"http","scheme":"bearer"}}},"paths":{"/v0/item/{id}.json":{"get":{"operationId":"getItemById","summary":"Get an item (story, comment, job, poll, pollopt) by numeric id","description":"Returns the JSON object for the item with the given integer id. Items include stories, comments, jobs, polls, and poll options. Always append .json to the path. Optionally add print=pretty for human-readable formatting. For live updates, you can open a Server-Sent Events stream by sending Accept: text/event-stream to the same URL; events will include item changes as they occur.","parameters":[{"name":"id","in":"path","description":"Numeric item id (unique integer). Example values are real Hacker News item ids.","required":true,"style":"simple","explode":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"name":"print","in":"query","description":"Optional pretty-printed JSON response.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Item found — returns the item object.","headers":{"Content-Type":{"description":"MIME type of the returned representation.","schema":{"type":"string","example":"application/json; charset=utf-8"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Unique item id."},"by":{"type":"string","description":"Author username."},"time":{"type":"integer","description":"Unix time (seconds since epoch) when the item was created."},"type":{"type":"string","description":"Item type.","enum":["job","story","comment","poll","pollopt"]},"title":{"type":"string","description":"Title (stories, jobs, polls)."},"url":{"type":"string","format":"uri","description":"Story or job URL, if present."},"text":{"type":"string","description":"HTML-formatted text for comments/stories/polls."},"score":{"type":"integer","description":"Score (points) for stories/polls."},"kids":{"type":"array","description":"Array of child item ids (e.g., comments).","items":{"type":"integer"}},"descendants":{"type":"integer","description":"Total comment count for stories/polls."},"parent":{"type":"integer","description":"Parent item id (for comments/pollopts)."},"poll":{"type":"integer","description":"Poll id to which this poll option belongs."},"parts":{"type":"array","description":"Array of related poll option ids for polls.","items":{"type":"integer"}},"deleted":{"type":"boolean","description":"True if the item is deleted."},"dead":{"type":"boolean","description":"True if the item is dead."}},"required":["id","time","type"]}}}},"400":{"description":"Bad request — e.g., non-integer id in path or malformed query parameter."},"404":{"description":"Not found — no item exists with the given id."},"429":{"description":"Too many requests — provider does not document rate limits, but requests may be throttled if you hammer the service."}}}},"/v0/user/{id}.json":{"get":{"operationId":"getUserById","summary":"Get a user profile by username","description":"Returns the user profile JSON for the given case-sensitive username. Only users with public activity are available through the API. Fields: id, created (Unix time), karma, about (HTML), submitted (array of item ids).","parameters":[{"name":"id","in":"path","description":"Case-sensitive username (user id).","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"print","in":"query","description":"Optional pretty-printed JSON output.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"User profile found.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Username."},"created":{"type":"integer","description":"Unix time when the account was created."},"karma":{"type":"integer","description":"User karma score."},"about":{"type":"string","description":"Optional HTML self-description."},"submitted":{"type":"array","description":"Array of item ids submitted by the user (stories, comments, polls, etc.).","items":{"type":"integer"}}},"required":["id","created","karma"]}}}},"400":{"description":"Bad request — malformed username."},"404":{"description":"Not found — no public user with that id exists."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/topstories.json":{"get":{"operationId":"getTopStories","summary":"Get list of up to 500 top story ids","description":"Returns an array of item ids representing the current top stories (may include job posts). Use these ids with /v0/item/{id}.json to fetch full item details. The ordering reflects current ranking and may change between requests.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of integer item ids (top stories).","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of top story ids (up to ~500)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — no explicit limit documented; back off and retry later."}}}},"/v0/newstories.json":{"get":{"operationId":"getNewStories","summary":"Get list of up to 500 new story ids","description":"Returns an array of the most recently submitted story ids (up to ~500). Use with /v0/item/{id}.json to fetch details.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of integer item ids (new stories).","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of new story ids (up to ~500)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/beststories.json":{"get":{"operationId":"getBestStories","summary":"Get list of best story ids","description":"Returns an array of ids for the current 'best' stories (up to ~500), reflecting a separate ranking from 'top'.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of integer item ids (best stories).","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of best story ids (up to ~500)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/askstories.json":{"get":{"operationId":"getAskStories","summary":"Get recent Ask HN story ids","description":"Returns up to ~200 of the latest Ask HN story ids.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of Ask HN story ids.","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of Ask HN story ids (up to ~200)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/showstories.json":{"get":{"operationId":"getShowStories","summary":"Get recent Show HN story ids","description":"Returns up to ~200 Show HN story ids.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of Show HN ids.","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of Show HN story ids (up to ~200)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/jobstories.json":{"get":{"operationId":"getJobStories","summary":"Get recent job story ids","description":"Returns up to ~200 job posting ids.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Array of job item ids.","content":{"application/json":{"schema":{"type":"array","items":{"type":"integer","description":"Item id."},"description":"Ordered list of job story ids (up to ~200)."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/updates.json":{"get":{"operationId":"getUpdates","summary":"Get recent updates (items and profiles)","description":"Returns recent changes to items and user profiles. The response is an object with items (array of item ids that changed) and profiles (array of usernames that changed). Useful for polling or streaming for recent changes.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Updates object containing arrays items and profiles.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Item ids that have changed recently.","items":{"type":"integer"}},"profiles":{"type":"array","description":"Usernames that have changed recently.","items":{"type":"string"}}},"required":["items","profiles"]}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}},"/v0/maxitem.json":{"get":{"operationId":"getMaxItem","summary":"Get the current largest item id (maxitem)","description":"Returns a single integer representing the current maximum item id. You can walk backward from this id to discover items.","parameters":[{"name":"print","in":"query","description":"Optional pretty-printed JSON.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["pretty"]}}],"responses":{"200":{"description":"Integer max item id.","content":{"application/json":{"schema":{"type":"integer","description":"Maximum item id currently present."}}}},"400":{"description":"Bad request — malformed query parameter."},"429":{"description":"Too many requests — slow down your polling."}}}}}}