{"openapi":"3.0.0","info":{"title":"TinyFish Search API","version":"1.0.0","description":"Get structured ranked web results for a query.","contact":{"name":"TinyFish Support","email":"support@tinyfish.ai"}},"servers":[{"url":"https://api.search.tinyfish.ai"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Get your key from the API Keys page."}},"schemas":{},"parameters":{}},"paths":{"/":{"get":{"operationId":"search","summary":"Search the web","description":"Search the web and get structured results. Returns ranked results with titles, snippets, and URLs.\n\n**Location and language resolution:**\n- If `location` is set but `language` is not, the language auto-resolves to the most predominantly used language in that country.\n- If `language` is set but `location` is not, the location auto-resolves to the country where that language is most predominantly used.\n- If neither `location` nor `language` is set, defaults to `US` and `en`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"Search query","example":"web automation tools"},"required":true,"description":"Search query","name":"query","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent.","example":"Find an open-source library for parsing PDF invoices in Python"},"required":false,"description":"Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent.","name":"purpose","in":"query"},{"schema":{"type":"string","description":"Country code for geo-targeted results","example":"US"},"required":false,"description":"Country code for geo-targeted results","name":"location","in":"query"},{"schema":{"type":"string","description":"Language code for result language","example":"en"},"required":false,"description":"Language code for result language","name":"language","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of domains to restrict results to","example":"github.com,arxiv.org"},"required":false,"description":"Comma-separated list of domains to restrict results to","name":"include_domains","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of domains to exclude from results","example":"pinterest.com,quora.com"},"required":false,"description":"Comma-separated list of domains to exclude from results","name":"exclude_domains","in":"query"},{"schema":{"type":"string","enum":["web","news","research_paper"],"description":"Type of search to perform: \"web\" for standard results, \"news\" for news articles, \"research_paper\" for academic papers. Defaults to \"web\".","example":"news"},"required":false,"description":"Type of search to perform: \"web\" for standard results, \"news\" for news articles, \"research_paper\" for academic papers. Defaults to \"web\".","name":"domain_type","in":"query"},{"schema":{"type":"string","description":"Return results after this date (YYYY-MM-DD)","example":"2024-01-01"},"required":false,"description":"Return results after this date (YYYY-MM-DD)","name":"after_date","in":"query"},{"schema":{"type":"string","description":"Return results before this date (YYYY-MM-DD)","example":"2024-12-31"},"required":false,"description":"Return results before this date (YYYY-MM-DD)","name":"before_date","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":5256000,"description":"Return results from the past N minutes (1 to 5,256,000).","example":60},"required":false,"description":"Return results from the past N minutes (1 to 5,256,000).","name":"recency_minutes","in":"query"},{"schema":{"type":"integer","minimum":0,"maximum":9999,"description":"Return research papers published on or after this year (0-9999, inclusive). Only supported for domain_type=research_paper.","example":2019},"required":false,"description":"Return research papers published on or after this year (0-9999, inclusive). Only supported for domain_type=research_paper.","name":"pub_year_min","in":"query"},{"schema":{"type":"integer","minimum":0,"maximum":9999,"description":"Return research papers published on or before this year (0-9999, inclusive). Only supported for domain_type=research_paper.","example":2022},"required":false,"description":"Return research papers published on or before this year (0-9999, inclusive). Only supported for domain_type=research_paper.","name":"pub_year_max","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":10,"description":"Page number for pagination, starting from 0 (max 10)","example":2},"required":false,"description":"Page number for pagination, starting from 0 (max 10)","name":"page","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"When \"true\", each result includes a thumbnail_url when available. Defaults to false.","example":"true"},"required":false,"description":"When \"true\", each result includes a thumbnail_url when available. Defaults to false.","name":"include_thumbnail","in":"query"},{"schema":{"type":"string","maxLength":256,"description":"JSON-encoded fetch configuration object.","example":"{}"},"required":false,"description":"JSON-encoded fetch configuration object.","name":"fetch","in":"query"}],"responses":{"200":{"description":"Search completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"The search query that was executed","example":"web automation tools"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","description":"Position in search results","example":1},"site_name":{"type":"string","description":"Site name","example":"example.com"},"snippet":{"type":"string","description":"Text snippet from the result","example":"This is an example snippet..."},"title":{"type":"string","description":"Page title","example":"Example Page"},"url":{"type":"string","format":"uri","description":"Result URL","example":"https://example.com/page"},"thumbnail_url":{"type":"string","format":"uri","description":"Thumbnail image URL, present only when include_thumbnail=true and a thumbnail is available","example":"https://example.com/thumb.jpg"},"fetch":{"nullable":true,"description":"Fetched page content, present only when fetch param is supplied"},"fetch_error":{"nullable":true,"description":"Fetch error details when fetch was requested. Contains details on failure; may be null when fetching succeeds."},"date":{"type":"string","description":"Publication date, present for news and some web results"},"publisher":{"type":"string","description":"Publisher name, present for news results when domain_type=news"},"authors":{"type":"array","items":{"type":"string"},"description":"Author list, present for academic results when domain_type=research_paper"},"venue":{"type":"string","description":"Journal or conference name, present when domain_type=research_paper"},"year":{"type":"integer","description":"Publication year, present when domain_type=research_paper"},"cited_by_count":{"type":"integer","description":"Citation count, present when domain_type=research_paper"},"pdf_url":{"type":"string","description":"PDF URL, present when domain_type=research_paper and a PDF is available"}},"required":["position","site_name","snippet","title","url"],"description":"A single search result"},"description":"Array of search results"},"total_results":{"type":"integer","description":"Total number of results","example":10},"page":{"type":"integer","description":"The current page number, starting from 0","example":0},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Present only when any result carries a fetch_error; include it when reporting failed fetches.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["query","results","total_results","page"],"description":"Search response with results"},"example":{"query":"web automation tools","results":[{"position":1,"site_name":"example.com","snippet":"Top web automation tools for 2026...","title":"Best Web Automation Tools","url":"https://example.com/web-automation-tools"}],"total_results":10,"page":0}}}},"400":{"description":"Invalid request - missing or invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required - daily free Search allowance used and the wallet balance is zero or below (`INSUFFICIENT_CREDITS`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"403":{"description":"Forbidden - Search request forbidden by the upstream service","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"404":{"description":"Search API is not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Search service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/usage":{"get":{"operationId":"listSearchUsage","summary":"List search usage","description":"List search usage records for the authenticated user. Returns paginated results with query details, status, and result counts.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"start_after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"end_before","in":"query"},{"schema":{"type":"string","enum":["completed","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Search usage retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"query":{"type":"string"},"status_code":{"type":"integer"},"result_count":{"type":"integer"},"results":{"type":"array","nullable":true,"items":{"type":"object","properties":{"position":{"type":"integer","description":"Position in search results","example":1},"site_name":{"type":"string","description":"Site name","example":"example.com"},"snippet":{"type":"string","description":"Text snippet from the result","example":"This is an example snippet..."},"title":{"type":"string","description":"Page title","example":"Example Page"},"url":{"type":"string","format":"uri","description":"Result URL","example":"https://example.com/page"},"thumbnail_url":{"type":"string","format":"uri","description":"Thumbnail image URL, present only when include_thumbnail=true and a thumbnail is available","example":"https://example.com/thumb.jpg"},"fetch":{"nullable":true,"description":"Fetched page content, present only when fetch param is supplied"},"fetch_error":{"nullable":true,"description":"Fetch error details when fetch was requested. Contains details on failure; may be null when fetching succeeds."},"date":{"type":"string","description":"Publication date, present for news and some web results"},"publisher":{"type":"string","description":"Publisher name, present for news results when domain_type=news"},"authors":{"type":"array","items":{"type":"string"},"description":"Author list, present for academic results when domain_type=research_paper"},"venue":{"type":"string","description":"Journal or conference name, present when domain_type=research_paper"},"year":{"type":"integer","description":"Publication year, present when domain_type=research_paper"},"cited_by_count":{"type":"integer","description":"Citation count, present when domain_type=research_paper"},"pdf_url":{"type":"string","description":"PDF URL, present when domain_type=research_paper and a PDF is available"}},"required":["position","site_name","snippet","title","url"],"description":"A single search result"}},"cached":{"type":"boolean","nullable":true},"response_size_bytes":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","request_id","query","status_code","result_count","results","cached","response_size_bytes","created_at"],"description":"A single search usage record"}},"total":{"type":"integer"},"limit":{"type":"integer"},"page":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}},"required":["items","total","limit","page","total_pages","has_more"],"description":"Paginated search usage response"},"example":{"items":[{"id":1,"request_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","query":"web automation tools","status_code":200,"result_count":10,"results":[{"position":1,"site_name":"example.com","snippet":"Top web automation tools for 2026...","title":"Best Web Automation Tools","url":"https://example.com/web-automation-tools"}],"cached":null,"response_size_bytes":4096,"created_at":"2026-01-14T10:30:00Z"}],"total":1,"limit":100,"page":1,"total_pages":1,"has_more":false}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"404":{"description":"Search API is not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Search service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}}}}