{ "openapi": "3.1.0", "info": { "title": "Andi AI Search API", "version": "1.7.0", "description": "Web search and page-fetch API for people and AI agents. `GET`/`POST /api/v1/search` returns structured results with query operators, domain and date filtering, and multiple output formats. `GET /api/v1/fetch` retrieves and extracts a single page. `GET /api/v1/news/:topic` returns a curated, ranked news feed for one of 27 fixed topics, with an optional `q` keyword filter. Search and fetch support `format=context`, which returns markdown suited to language models; the news endpoint also returns RSS and an HTML widget. By default (`searchMode=auto`) the API sets the search effort per query — compute, models, and depth — automatically; the fixed modes (`low-cost`, `fast`, `balanced`, `deep`, `exhaustive`) pin an effort level when you want the same behavior on every call. Requests are billed on outcome-based pricing, reported per call in `metrics.cost_dollars`." }, "servers": [ { "url": "https://api.andiai.com", "description": "Production" } ], "security": [ { "apiKey": [] } ], "paths": { "/api/v1/search": { "get": { "operationId": "search", "summary": "Search the web", "description": "Performs a web search and returns structured results. Search effort is set automatically per query by default (`searchMode=auto`), with fixed modes (low-cost, fast, balanced, deep, exhaustive) available for manual control. Supports domain and date filtering, query operators, and multiple output formats.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query string. Supports query operators when `parseOperators` is enabled. You can also pass a JSON array of up to 5 queries for multi-query searches (e.g., `[\"query one\", \"query two\"]`).", "schema": { "type": "string" }, "example": "best programming languages" }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip for pagination.", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "searchMode", "in": "query", "description": "Search effort control. `auto` (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: `low-cost` caps the work done per request for budget-constrained callers. `fast` returns results in about 1.2 seconds. `balanced` is everyday web search, about 3–4 seconds. `deep` searches from multiple angles with spell correction, about 6.5 seconds. `exhaustive` is Andi's most thorough mode: more sources and more time, up to about 15 seconds; for a question with several parts or steps it searches each part. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see `metrics.cost_dollars`).", "schema": { "type": "string", "enum": [ "auto", "low-cost", "fast", "balanced", "deep", "exhaustive" ], "default": "auto" } }, { "name": "effort", "in": "query", "description": "Thoroughness dial, independent of `searchMode`: `low` favors speed, `medium` is balanced, `high` searches from multiple angles with spell correction, `max` gives the most complete results and also searches each part of a question that has several parts or steps — the same tiers as pinning `searchMode` to `fast`, `balanced`, `deep`, and `exhaustive` respectively. An explicit `searchMode` always wins over `effort`. With the default `auto` mode, an explicit `effort` pins its equivalent mode. Omit for the adaptive default. Invalid values return a `400` listing the valid tiers.", "schema": { "type": "string", "enum": [ "low", "medium", "high", "max" ] } }, { "name": "reranker", "in": "query", "description": "Semantic reranker size hint. `small` is the lightest and fastest; `medium` and above apply stronger relevance scoring but need a deeper `searchMode` and may be clamped by the request's time and cost budget (for example, `xl` needs `deep` or `exhaustive`). `auto` (default) selects a tier automatically based on the query and search mode.", "schema": { "type": "string", "enum": [ "auto", "small", "medium", "large", "xl" ], "default": "auto" } }, { "name": "intent", "in": "query", "description": "Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like `search`, `news`, `video`, `images`, `weather`, `wiki`, `code`, `recipe`, `place`, `time`, and others. Set `none` to disable intent detection entirely; `auto` is equivalent to omitting the parameter.", "schema": { "type": "string" }, "examples": { "news": { "value": "news", "summary": "Latest news results" }, "video": { "value": "video", "summary": "Video search results" }, "images": { "value": "images", "summary": "Image search results" }, "weather": { "value": "weather", "summary": "Weather data" }, "wiki": { "value": "wiki", "summary": "Wikipedia/knowledge results" }, "code": { "value": "code", "summary": "Programming-related results" }, "recipe": { "value": "recipe", "summary": "Recipe results" }, "place": { "value": "place", "summary": "Business/place results" }, "time": { "value": "time", "summary": "Time query results" } } }, { "name": "format", "in": "query", "description": "Response format. `json` returns a JSON object. `context` returns results as markdown text, suitable for passing to language models.", "schema": { "type": "string", "enum": [ "json", "context" ], "default": "json" } }, { "name": "metadata", "in": "query", "description": "Level of metadata to include. `basic` includes standard search metrics. `full` includes extended metadata with content type details and reader data on results.", "schema": { "type": "string", "enum": [ "basic", "full" ], "default": "basic" } }, { "name": "extracts", "in": "query", "description": "Include text extracts from result pages in the response. Defaults to `true` when `format=context`, `content=true` or `content=focused`; pass `extracts=false` to turn them off in those cases. Also returned by default with `metadata=full`.", "schema": { "type": "boolean", "default": false } }, { "name": "content", "in": "query", "description": "Include each result's full page text, in `reader.markdown` (or `reader.content` when the page has no markdown version). `true` returns the head of each page. `focused` returns the parts of each page that answer the query, in page order under section headings; it is billed and capped like `true` and falls back to the normal page text when no focused text can be built. Any other value is treated as `false`. Also turns on `extracts` unless `extracts=false` is passed. Adds time and cost; deeper modes allow more time.", "schema": { "type": "string", "enum": ["true", "focused", "false"], "default": "false" } }, { "name": "enrichContent", "in": "query", "deprecated": true, "description": "Deprecated alias of `content`. Retained for backward compatibility; use `content` instead.", "schema": { "type": "boolean", "default": false } }, { "name": "maxContentLength", "in": "query", "description": "Maximum number of characters of enriched content to return per result. Only applies when `content` (or its deprecated alias `enrichContent`) is true.", "schema": { "type": "integer" } }, { "name": "timeout", "in": "query", "description": "Target time in milliseconds for ranked results (1000–30000). It is a target, not a hard ceiling. Omit it for the mode's normal speed; a larger value (e.g. 30000) lets slower sources run longer, so deep/exhaustive searches can take close to that long. The search may run a little past it when it needs a moment more to return a useful page. Requested page text (`content`/`extracts`) is fetched afterward, on top of the target. Values below 1000 are raised to 1000; values above 30000 are lowered to 30000; 0, empty or non-numeric values are ignored. With `searchMode=auto` (the default), a timeout steps the resolved mode down to the richest one that fits it. An explicit `searchMode` is always honored.", "schema": { "type": "integer", "minimum": 1000, "maximum": 30000 } }, { "name": "safe", "in": "query", "description": "Safe search filtering level. `off` disables filtering, `moderate` filters most explicit content, `strict` applies maximum filtering.", "schema": { "type": "string", "enum": [ "off", "moderate", "strict" ], "default": "off" } }, { "name": "country", "in": "query", "description": "Two-letter ISO 3166-1 country code to localize results.", "schema": { "type": "string", "default": "US" }, "example": "US" }, { "name": "sourceCountry", "in": "query", "description": "Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike `country`, which biases results by locale, `sourceCountry` excludes results from other countries.", "schema": { "type": "string" }, "example": "GB" }, { "name": "language", "in": "query", "description": "Preferred language for results, as an ISO 639-1 code.", "schema": { "type": "string", "default": "en" }, "example": "en" }, { "name": "units", "in": "query", "description": "Unit system for weather and calculation results. Defaults based on the `country` parameter — `imperial` for `US`, `metric` for all other countries.", "schema": { "type": "string", "enum": [ "metric", "imperial" ] } }, { "name": "noCache", "in": "query", "description": "Bypass cached results and fetch fresh data.", "schema": { "type": "boolean", "default": false } }, { "name": "dateRange", "in": "query", "description": "Relative date range filter for results.", "schema": { "type": "string", "enum": [ "day", "week", "month", "year", "24h", "7d", "30d", "90d", "1y" ] } }, { "name": "dateFrom", "in": "query", "description": "Filter results published on or after this date. Format: `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date" }, "example": "2025-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter results published on or before this date. Format: `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "includeDomains", "in": "query", "description": "Comma-separated list of domains to restrict results to. Supports wildcards (`*.example.com`).", "schema": { "type": "string" }, "example": "github.com,stackoverflow.com" }, { "name": "excludeDomains", "in": "query", "description": "Comma-separated list of domains to exclude from results. Supports wildcards.", "schema": { "type": "string" }, "example": "pinterest.com,reddit.com" }, { "name": "includeTerms", "in": "query", "description": "Comma-separated terms that must appear in results.", "schema": { "type": "string" } }, { "name": "excludeTerms", "in": "query", "description": "Comma-separated terms to exclude from results.", "schema": { "type": "string" } }, { "name": "parseOperators", "in": "query", "description": "Parse query operators (like `site:`, `filetype:`, `intitle:`) from the query string. When disabled, the query is treated as literal text.", "schema": { "type": "boolean", "default": true } }, { "name": "linkFormat", "in": "query", "description": "Field name for result URLs. Use `url` to receive the URL field as `url` instead of the default `link`. Only affects the `/search` endpoint.", "schema": { "type": "string", "enum": [ "link", "url" ], "default": "link" } }, { "name": "imageFormat", "in": "query", "description": "Field naming for image results. `long` (default) uses full field names. `short` uses abbreviated field names.", "schema": { "type": "string", "enum": [ "short", "long" ], "default": "long" } }, { "name": "filetype", "in": "query", "description": "Filter results by file type.", "schema": { "type": "string" }, "example": "pdf" }, { "name": "intitle", "in": "query", "description": "Filter results to pages with this term in the title.", "schema": { "type": "string" } }, { "name": "inurl", "in": "query", "description": "Filter results to pages with this term in the URL.", "schema": { "type": "string" } }, { "name": "intext", "in": "query", "description": "Filter results to pages with this term in the body text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results. JSON by default; LLM-ready markdown with YAML frontmatter when `format=context`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/markdown": { "schema": { "type": "string", "description": "Markdown results with YAML frontmatter, returned when `format=context`." } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing required parameter: q", "message": "The q parameter is required" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized", "message": "Invalid API key" } } } }, "402": { "description": "Insufficient credits — account balance depleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Insufficient Credits", "message": "Your account has insufficient credits. Please add credits to continue." } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Too Many Requests", "message": "Rate limit of N requests per second exceeded" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error", "message": "Unknown error" } } } } } }, "post": { "operationId": "searchPost", "summary": "Search the web (JSON body)", "description": "Same contract as `GET /api/v1/search`, but accepts parameters as a JSON body. Preferred for location-bearing requests because GET-style location encoding is awkward and keeps `latitude`/`longitude` out of HTTP access logs. All GET query parameters are accepted as body fields, plus optional location fields (`latitude`, `longitude`, `accuracy`, `city`, `state`, `countryCode`, `postalCode`, `timezone`, `location`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "Search query string. Same semantics as the GET `q` parameter." }, "limit": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100, "description": "Maximum number of results to return." }, "offset": { "type": "integer", "default": 0, "minimum": 0, "description": "Number of results to skip for pagination." }, "searchMode": { "type": "string", "enum": [ "auto", "low-cost", "fast", "balanced", "deep", "exhaustive" ], "default": "auto", "description": "Search effort control. `auto` (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: `low-cost` caps the work done per request for budget-constrained callers. `fast` returns results in about 1.2 seconds. `balanced` is everyday web search, about 3–4 seconds. `deep` searches from multiple angles with spell correction, about 6.5 seconds. `exhaustive` is Andi's most thorough mode: more sources and more time, up to about 15 seconds; for a question with several parts or steps it searches each part. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see `metrics.cost_dollars`)." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ], "description": "Thoroughness dial, independent of `searchMode`: `low` favors speed, `medium` is balanced, `high` searches from multiple angles with spell correction, `max` gives the most complete results and also searches each part of a question that has several parts or steps — the same tiers as pinning `searchMode` to `fast`, `balanced`, `deep`, and `exhaustive` respectively. An explicit `searchMode` always wins over `effort`. With the default `auto` mode, an explicit `effort` pins its equivalent mode. Omit for the adaptive default. Invalid values return a `400` listing the valid tiers." }, "reranker": { "type": "string", "enum": [ "auto", "small", "medium", "large", "xl" ], "default": "auto", "description": "Semantic reranker size hint. `small` is the lightest and fastest; `medium` and above apply stronger relevance scoring but need a deeper `searchMode` and may be clamped by the request's time and cost budget (for example, `xl` needs `deep` or `exhaustive`). `auto` (default) selects a tier automatically based on the query and search mode." }, "intent": { "type": "string", "description": "Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like `search`, `news`, `video`, `images`, `weather`, `wiki`, `code`, `recipe`, `place`, `time`, and others." }, "format": { "type": "string", "enum": [ "json", "context" ], "default": "json", "description": "Response format. `json` returns a JSON object. `context` returns results as markdown text, suitable for passing to language models." }, "metadata": { "type": "string", "enum": [ "basic", "full" ], "default": "basic", "description": "Level of metadata to include. `basic` includes standard search metrics. `full` includes extended metadata with content type details and reader data on results." }, "extracts": { "type": "boolean", "default": false, "description": "Include text extracts from result pages in the response. Defaults to `true` when `format=context`, `content=true` or `content=focused`; pass `extracts=false` to turn them off in those cases. Also returned by default with `metadata=full`." }, "content": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "focused", "false"] } ], "default": false, "description": "Include each result's full page text, in `reader.markdown` (or `reader.content` when the page has no markdown version). `true` returns the head of each page. `\"focused\"` returns the parts of each page that answer the query, in page order under section headings; it is billed and capped like `true` and falls back to the normal page text when no focused text can be built. Any other value is treated as `false`. Also turns on `extracts` unless `extracts=false` is passed. Adds time and cost; deeper modes allow more time." }, "enrichContent": { "type": "boolean", "default": false, "deprecated": true, "description": "Deprecated alias of `content`." }, "maxContentLength": { "type": "integer", "description": "Maximum number of characters of page text to return per result. Only applies when `content` is true." }, "timeout": { "type": "integer", "minimum": 1000, "maximum": 30000, "description": "Target time in milliseconds for ranked results (1000–30000). It is a target, not a hard ceiling. Omit it for the mode's normal speed; a larger value (e.g. 30000) lets slower sources run longer, so deep/exhaustive searches can take close to that long. The search may run a little past it when it needs a moment more to return a useful page. Requested page text (`content`/`extracts`) is fetched afterward, on top of the target. Values below 1000 are raised to 1000; values above 30000 are lowered to 30000; 0, empty or non-numeric values are ignored. With `searchMode=auto` (the default), a timeout steps the resolved mode down to the richest one that fits it. An explicit `searchMode` is always honored." }, "safe": { "type": "string", "enum": [ "off", "moderate", "strict" ], "default": "off", "description": "Safe search filtering level. `off` disables filtering, `moderate` filters most explicit content, `strict` applies maximum filtering." }, "country": { "type": "string", "default": "US", "description": "Two-letter ISO 3166-1 country code to localize results." }, "sourceCountry": { "type": "string", "description": "Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike `country`, which biases results by locale, `sourceCountry` excludes results from other countries." }, "language": { "type": "string", "default": "en", "description": "Preferred language for results, as an ISO 639-1 code." }, "units": { "type": "string", "enum": [ "metric", "imperial" ], "description": "Unit system for weather and calculation results. Defaults based on the `country` parameter — `imperial` for `US`, `metric` for all other countries." }, "noCache": { "type": "boolean", "default": false, "description": "Bypass cached results and fetch fresh data." }, "dateRange": { "type": "string", "enum": [ "day", "week", "month", "year", "24h", "7d", "30d", "90d", "1y" ], "description": "Relative date range filter for results." }, "dateFrom": { "type": "string", "format": "date", "description": "Filter results published on or after this date. Format: `YYYY-MM-DD`." }, "dateTo": { "type": "string", "format": "date", "description": "Filter results published on or before this date. Format: `YYYY-MM-DD`." }, "includeDomains": { "type": "string", "description": "Comma-separated list of domains to restrict results to. Supports wildcards (`*.example.com`)." }, "excludeDomains": { "type": "string", "description": "Comma-separated list of domains to exclude from results. Supports wildcards." }, "includeTerms": { "type": "string", "description": "Comma-separated terms that must appear in results." }, "excludeTerms": { "type": "string", "description": "Comma-separated terms to exclude from results." }, "parseOperators": { "type": "boolean", "default": true, "description": "Parse query operators (like `site:`, `filetype:`, `intitle:`) from the query string. When disabled, the query is treated as literal text." }, "linkFormat": { "type": "string", "enum": [ "link", "url" ], "default": "link", "description": "Field name for result URLs. Use `url` to receive the URL field as `url` instead of the default `link`. Only affects the `/search` endpoint." }, "imageFormat": { "type": "string", "enum": [ "short", "long" ], "default": "long", "description": "Field naming for image results. `long` (default) uses full field names. `short` uses abbreviated field names." }, "filetype": { "type": "string", "description": "Filter results by file type." }, "intitle": { "type": "string", "description": "Filter results to pages with this term in the title." }, "inurl": { "type": "string", "description": "Filter results to pages with this term in the URL." }, "intext": { "type": "string", "description": "Filter results to pages with this term in the body text." }, "latitude": { "type": "number", "description": "Latitude in decimal degrees. Sent in the body to keep coordinates out of HTTP access logs." }, "longitude": { "type": "number", "description": "Longitude in decimal degrees." }, "accuracy": { "type": "number", "description": "Location accuracy in meters." }, "city": { "type": "string", "description": "City name for location-aware queries." }, "state": { "type": "string", "description": "State or region name." }, "countryCode": { "type": "string", "description": "Two-letter ISO 3166-1 country code for the caller's location." }, "postalCode": { "type": "string", "description": "Postal or ZIP code." }, "timezone": { "type": "string", "description": "IANA timezone, for example America/Los_Angeles." }, "location": { "type": "string", "description": "Display name for the caller's location, for example \"San Francisco, CA\"." } } }, "example": { "q": "best italian restaurants near me", "limit": 10, "city": "San Francisco", "state": "California", "countryCode": "US", "latitude": 37.7794, "longitude": -122.4176 } } } }, "responses": { "200": { "description": "Search results. JSON by default; LLM-ready markdown with YAML frontmatter when `format=context`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/markdown": { "schema": { "type": "string", "description": "Markdown results with YAML frontmatter, returned when `format=context`." } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — account balance depleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/fetch": { "get": { "summary": "Fetch a web page", "description": "Fetches a single web page and returns clean extracted content (title, article text, metadata) as JSON, or LLM-ready markdown with format=context. The companion to /api/v1/search: search, pick a result, fetch it in full.", "operationId": "fetchPage", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full http(s) URL of the page to fetch.", "schema": { "type": "string", "format": "uri" } }, { "name": "format", "in": "query", "required": false, "description": "Response format: json (structured, default) or context (LLM-ready markdown).", "schema": { "type": "string", "enum": [ "json", "context" ], "default": "json" } }, { "name": "effort", "in": "query", "required": false, "description": "How thoroughly to retrieve the page: `low` favors speed, `max` spends the most time extracting content — useful for pages that are slow to load or render content client-side. Omit for the server's adaptive default. Invalid values return a `400` listing the valid tiers. Fetch failures (`422`, `503`) are never billed, regardless of `effort`.", "schema": { "type": "string", "enum": [ "low", "medium", "high", "max" ] } }, { "name": "maxContentLength", "in": "query", "required": false, "description": "Maximum content characters to return (default 100000, maximum 200000).", "schema": { "type": "integer", "default": 100000, "minimum": 1, "maximum": 200000 } }, { "name": "query", "in": "query", "required": false, "description": "Optional query string to scope extraction to. When set, the response includes `query_extracts`, `query_snippet`, and `query_hash` fields scoped to this query.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extracted page content", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string", "description": "Clean extracted text content" }, "markdown": { "type": "string", "description": "Clean extracted content as markdown, when available." }, "extracts": { "type": "array", "items": { "type": "string" }, "description": "Key passage extracts from the page, when available." }, "snippet": { "type": "string", "description": "Short excerpt from the page." }, "author": { "type": "string" }, "date": { "type": "string" }, "site_name": { "type": "string" }, "image": { "type": "string" }, "lang": { "type": "string" }, "word_count": { "type": "integer" }, "truncated": { "type": "boolean" }, "query_extracts": { "type": "array", "items": { "type": "string" }, "description": "Text extracts from the page most relevant to `query`. Only present when `query` is set." }, "query_snippet": { "type": "string", "description": "Short excerpt from the page most relevant to `query`. Only present when `query` is set." }, "query_hash": { "type": "string", "description": "Hash identifying the `query` used to scope this response. Only present when `query` is set." }, "partial": { "type": "boolean", "description": "Whether this is a partial response returned before the page finished retrieving. Only present when true." }, "retry_after_seconds": { "type": "integer", "description": "Seconds to wait before retrying for the full content. Only present on partial responses." }, "metrics": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "cost_dollars": { "type": "number", "description": "Actual cost of this fetch in USD (post-discount). Failed fetches are not billed." } } } } } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Missing or invalid url parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credit balance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The page was reached but its content could not be extracted. Not retriable. Not billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The page is still being retrieved, or a transient failure occurred. Retriable — retry after the number of seconds in the `Retry-After` header. Not billed.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Content warming", "message": "The page is still being retrieved. Retry in 5s for the full content.", "retry_after_seconds": 5, "url": "https://example.com/article" } } } } } } }, "/api/v1/news": { "get": { "operationId": "listNewsTopics", "summary": "List news topics", "description": "Lists every topic available at `GET /api/v1/news/{topic}` with its title, category, supported formats, whether a detailed brief is available and its recent story count. Requires an API key; not billed. A feed key can be sent in the `key` query parameter. Add `format=html` for a page of ready links.", "parameters": [ { "name": "key", "in": "query", "required": false, "description": "A feed key, for links that cannot send a header. Only feed keys are accepted here; a full API key in a URL returns `403`.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "`json` (default) returns the topics list. `html` returns the same list as a page of ready links; a feed key is added to every link. Any other value returns the JSON list.", "schema": { "type": "string", "enum": [ "json", "html" ], "default": "json" } } ], "responses": { "200": { "description": "Topics index", "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Topic slug to use in `/api/v1/news/{topic}`." }, "title": { "type": "string", "description": "Plain-language description of the feed." }, "category": { "type": "string", "enum": [ "news", "region", "extended", "group" ], "description": "Section the topic belongs to." }, "formats": { "type": "array", "items": { "type": "string" }, "description": "Supported `format` values." }, "detail": { "type": "array", "items": { "type": "string", "enum": [ "full" ] }, "description": "`[\"full\"]` when the topic has a detailed brief (`detail=full`); otherwise empty." }, "count_48h": { "type": [ "integer", "null" ], "description": "Stories in the last 48 hours. `null` for the curated groups (`top`, `hn-frontpage`, `ai-news`, `tech-news`), where a per-topic count does not apply, and for every topic if the count is temporarily unavailable." } }, "required": [ "slug", "title", "category", "formats", "detail", "count_48h" ] } }, "hours": { "type": "integer", "description": "Window the counts cover, in hours." }, "count": { "type": "integer", "description": "Number of topics." } }, "required": [ "topics", "hours", "count" ] } }, "text/html": { "schema": { "type": "string", "description": "A web page of ready links for every topic (RSS, widget, ticker, detailed brief). Returned only for `format=html`." } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized", "message": "Invalid API key" } } } }, "402": { "description": "Insufficient credits — account balance depleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Insufficient Credits", "message": "Your account has insufficient credits. Please add credits to continue." } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Too Many Requests", "message": "Rate limit of N requests per second exceeded" } } } } } } }, "/api/v1/news/{topic}": { "get": { "operationId": "getNewsFeed", "summary": "Get a curated news feed", "description": "Returns a curated, ranked news feed for a fixed topic. The topic path segment selects the feed; an optional `q` filters it by keyword. `results` are ordered by relevance (a semantic pass tuned to the topic, weighted toward fresher articles); `news` holds the same articles in strict reverse-chronological order. `images` includes article images when available. When a pre-written brief exists for the topic it is returned in `aiSummary` (also in `answer`); a response to a `q` request carries no brief. Choose the output with `format`: `json` (default), `context` (markdown for LLMs), `rss` (RSS 2.0), `embed` (an HTML widget) or `ticker` (a scrolling headline bar). Links that cannot send a header, such as an `