{"openapi":"3.1.0","info":{"title":"Hacker News API (Bowmark)","version":"e833508f87ff","description":"Hacker News (news.ycombinator.com) — the current top / new / best / Ask HN / Show HN / job stories with title, link, points and comment count, one item (story or comment) by id, and keyword search over every HN story or every HN comment (with a date window), and full nested comment threads, through HN's own public API.\n\nEvery function Bowmark has for Hacker News (news.ycombinator.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/hackernews/topStories":{"post":{"operationId":"topStories","summary":"The stories on the Hacker News front page right now, in rank order — title, link, points, author, comment count and the HN discussion url.","description":"The stories on the Hacker News front page right now, in rank order — title, link, points, author, comment count and the HN discussion url. `list` picks top (default), new, best, ask, show or job; `limit` is 1-30, default 10. For list top, `kids` comes back empty (the bodies come from HN's search index, which has no reply ids); call getItem(id) for a story's reply ids. Example: topStories({ limit: 5 }).\n\nCalls `bowmark.providers.hackernews.topStories`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<HackerNewsItem[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/HackerNewsTopStoriesArgs","description":"TypeScript: `HackerNewsTopStoriesArgs`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/hackernews/getItem":{"post":{"operationId":"getItem","summary":"One Hacker News item — a story, comment, job or poll — by its numeric id or news.ycombinator.com/item?id= url.","description":"One Hacker News item — a story, comment, job or poll — by its numeric id or news.ycombinator.com/item?id= url. `kids` holds the ids of its direct replies, so a thread is read by calling getItem on them. THROWS on an id HN has no item for. Example: getItem(8863).\n\nCalls `bowmark.providers.hackernews.getItem`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<HackerNewsItem>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number","description":"TypeScript: `number`"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/hackernews/search":{"post":{"operationId":"search","summary":"Keyword search over every Hacker News story, through HN's own search (hn.algolia.com) — up to 20 hits ranked by relevance with title, link, points, comment count and date.","description":"Keyword search over every Hacker News story, through HN's own search (hn.algolia.com) — up to 20 hits ranked by relevance with title, link, points, comment count and date. Returns [] on no match. Example: search(\"rust\").\n\nCalls `bowmark.providers.hackernews.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<HackerNewsSearchHit[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"TypeScript: `string`"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/hackernews/searchComments":{"post":{"operationId":"searchComments","summary":"Search Hacker News comments for community discussion and opinion on a topic.","description":"Search Hacker News comments for community discussion and opinion on a topic. Keyword search over every Hacker News comment (not just stories), through HN's own search (hn.algolia.com) — what the community said. Each hit has the plain-text comment, author, post date, and the story it was posted under. `since` / `until` filter by date (ISO date or unix seconds); `sort` is \"relevance\" (default) or \"date\" (newest first); `limit` 1-100, default 20. Research community opinion and discussion. Returns [] on no match. Example: searchComments({ query: \"rust\", since: \"2026-01-01\" }).\n\nCalls `bowmark.providers.hackernews.searchComments`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<HackerNewsCommentHit[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/HackerNewsSearchCommentsArgs"}],"description":"TypeScript: `string | HackerNewsSearchCommentsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/hackernews/getThread":{"post":{"operationId":"getThread","summary":"One Hacker News story or comment with its entire nested comment thread in one call — every reply, every reply-to-reply, to the specified depth.","description":"One Hacker News story or comment with its entire nested comment thread in one call — every reply, every reply-to-reply, to the specified depth. Takes { id, depth? } (or a bare id). Returns the top-level item with all comments arranged as nested `replies`. `depth` caps how many levels of replies come back, 1-100, default 100 (the whole tree). A story with 300+ comments returns in one request. THROWS on an id HN has no item for. Example: getThread({ id: 8863, depth: 2 }).\n\nCalls `bowmark.providers.hackernews.getThread`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<HackerNewsThread>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"anyOf":[{"$ref":"#/components/schemas/HackerNewsGetThreadArgs"},{"type":"number"},{"type":"string"}],"description":"TypeScript: `HackerNewsGetThreadArgs | number | string`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}},"HackerNewsGetThreadArgs":{"type":"object","properties":{"id":{"anyOf":[{"type":"number"},{"type":"string"}]},"depth":{"type":"number"}},"required":["id"],"additionalProperties":true},"HackerNewsSearchCommentsArgs":{"type":"object","properties":{"query":{"type":"string"},"since":{"anyOf":[{"type":"string"},{"type":"number"}]},"until":{"anyOf":[{"type":"string"},{"type":"number"}]},"sort":{"anyOf":[{"const":"relevance"},{"const":"date"}]},"limit":{"type":"number"}},"required":["query"],"additionalProperties":true},"HackerNewsTopStoriesArgs":{"type":"object","properties":{"list":{"anyOf":[{"const":"top"},{"const":"new"},{"const":"best"},{"const":"ask"},{"const":"show"},{"const":"job"}]},"limit":{"type":"number"}},"additionalProperties":true}}}}