{"openapi":"3.1.0","info":{"title":"SERPdive API","version":"1.0.0","description":"AI Search API: POST /v1/search takes a question and returns answer-ready page content — extracted, cleaned, and sized for an LLM.","contact":{"email":"hello@serpdive.com","url":"https://serpdive.com"}},"servers":[{"url":"https://api.serpdive.com"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/search":{"post":{"operationId":"search","summary":"Search the web and get extracted, LLM-ready content","description":"Localization is automatic: the query's language picks where we search — there is no country parameter. Mako answers in a few seconds; Moby reads whole pages and can take substantially longer (we recommend an 80-second client timeout). Failed searches are never billed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"examples":{"basic":{"summary":"Basic search","value":{"query":"what happened between Trump and FIFA","model":"mako"}},"withAnswer":{"summary":"Deep search with a written, cited answer","value":{"query":"who won the 2026 Champions League final","model":"moby","verdict":true}}}}}},"responses":{"200":{"description":"Successful search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Malformed request: `bad_json` or `missing_query`. Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No usable key in the Authorization header: `missing_api_key` or `invalid_api_key`. The search never runs; nothing is billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The search couldn't complete: `upstream_timeout` or `upstream_error`. Safe to retry. Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Momentarily out of capacity: `pool_empty`, `region_unavailable` or `auth_unavailable`. May carry a `retry-after` header — honor it, then retry. Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from https://serpdive.com/dashboard/keys, sent as `Authorization: Bearer sd_live_…`."}},"schemas":{"SearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":300,"description":"The question, as you'd ask it. Longer queries are truncated, not rejected."},"model":{"type":"string","enum":["mako","moby"],"default":"mako","description":"Retrieval depth. `mako` (1 credit) returns the fact-carrying sentences of each source; `moby` (1.5 credits) returns the full readable content of every page. Unknown values fall back to `mako`."},"verdict":{"type":"boolean","default":false,"description":"Opt-in direct answer built from the sources — concise on Mako, detailed with `[n]` citations on Moby. Included in the price, never extra credits."}}},"SearchResponse":{"type":"object","required":["query","results"],"properties":{"query":{"type":"string","description":"Your query, echoed untouched."},"model":{"type":"string","enum":["mako","moby"],"description":"The model that answered."},"response_time_ms":{"type":["number","null"],"description":"Wall-clock time we took, in milliseconds."},"verdict":{"type":["string","null"],"description":"The written answer when `verdict: true` was sent and one could be built from the sources; null otherwise."},"extra_info":{"oneOf":[{"$ref":"#/components/schemas/ExtraInfo"},{"type":"null"}],"description":"A structured direct-answer block when the query has one — weather, exchange rates, definitions, live scores…; null when the query doesn't call for one."},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"},"description":"The extracted sources, best first."}}},"Result":{"type":"object","required":["url","content"],"properties":{"url":{"type":"string","format":"uri","description":"Source URL, tracking parameters stripped."},"title":{"type":["string","null"],"description":"Page title when one was found."},"date":{"type":"string","description":"Publication date when one was found (ISO 8601). Absent otherwise."},"content":{"type":"string","description":"The extraction — fact-carrying sentences on Mako, the full readable page on Moby."},"fallback":{"type":"boolean","description":"True when `content` is a short excerpt rather than a full page extraction. Absent otherwise."}}},"ExtraInfo":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["weather","finance","currency","calculator","dictionary","time","translation","standings","entity","featured_snippet"],"description":"Which kind of direct-answer block this is. Other fields depend on the type."}},"additionalProperties":true},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"detail":{"type":"string","description":"Human-readable context, when available."}}}}},"x-credits":{"monthlyFreeCredits":1000,"perSearch":{"mako":1,"moby":1.5},"note":"The verdict answer is always included. Failed searches (non-200) are never billed."}}