{"openapi":"3.1.0","info":{"title":"OmniScout API","version":"0.0.1","description":"Cloud API for OmniScout semantic search, grounded answers, and browser/computer Sprite sessions. All responses include a request_id for debugging."},"servers":[{"url":"https://api.omniscout.xyz","description":"API server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"OmniScout API key (os_live_...)"},"sessionSecret":{"type":"apiKey","in":"header","name":"x-session-secret","description":"Session secret returned once at session creation"}},"schemas":{},"parameters":{}},"paths":{"/v0/search":{"post":{"description":"Semantic web search powered by OmniScout","summary":"Search","tags":["OmniScout"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10},"zdr":{"type":"boolean"}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"query":{"type":"string"},"count":{"type":"integer"},"hits":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"source":{"type":"string"},"score":{"type":"number","nullable":true},"rank":{"type":"number","nullable":true},"published_at":{"type":"string","nullable":true},"indexed_at":{"type":"string","nullable":true},"effective_date":{"type":"string","nullable":true}},"required":["url","title","snippet"]}}},"required":["request_id","query","count","hits"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/answer":{"post":{"description":"Grounded one-sentence answer from web sources","summary":"Answer","tags":["OmniScout"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"zdr":{"type":"boolean"}},"required":["query"]}}}},"responses":{"200":{"description":"Answer with supporting sources","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"query":{"type":"string"},"answer":{"type":"string","nullable":true},"status":{"type":"string","enum":["answered","insufficient_information"]},"confidence":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"}},"required":["url"]}},"supports":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"source":{"type":"string"},"score":{"type":"number","nullable":true}},"required":["url"]}}},"required":["request_id","query","answer","status","confidence","sources"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/sessions":{"post":{"description":"Create an ephemeral cloud session","summary":"Create session","tags":["Sessions"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["browser","computer"],"default":"computer"},"ttl_seconds":{"type":"integer","minimum":60,"maximum":86400},"zdr":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"session_id":{"type":"string"},"session_secret":{"type":"string"},"status":{"type":"string","enum":["starting","ready","active","destroyed","failed"]},"type":{"type":"string","enum":["browser","computer"]},"capabilities":{"type":"array","items":{"type":"string","enum":["browser","computer","terminal","files","screenshots"]}},"created_at":{"type":"number"},"expires_at":{"type":"number"},"zdr":{"type":"boolean"}},"required":["request_id","session_id","session_secret","status","type","capabilities","created_at","expires_at"]}}}}}}},"/v0/sessions/{id}":{"get":{"description":"Get session status and capabilities","summary":"Get session","tags":["Sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session status","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"session_id":{"type":"string"},"status":{"type":"string","enum":["starting","ready","active","destroyed","failed"]},"type":{"type":"string","enum":["browser","computer"]},"capabilities":{"type":"array","items":{"type":"string","enum":["browser","computer","terminal","files","screenshots"]}},"created_at":{"type":"number"},"expires_at":{"type":"number"},"ready_at":{"type":"number","nullable":true},"failure_reason":{"type":"string","nullable":true}},"required":["request_id","session_id","status","type","capabilities","created_at","expires_at"]}}}}}},"delete":{"description":"Destroy a session","summary":"Delete session","tags":["Sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session deleted","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"session_id":{"type":"string"}},"required":["request_id","deleted","session_id"]}}}}}}},"/v0/sessions/{id}/actions":{"post":{"description":"Execute a primitive action on a session","summary":"Session action","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","minLength":1},"args":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"session":{"type":"string","default":"default"},"timeout_ms":{"type":"integer","minimum":0,"exclusiveMinimum":true},"zdr":{"type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"ok":{"type":"boolean"},"action":{"type":"string"},"data":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"error_kind":{"type":"string","nullable":true},"elapsed_ms":{"type":"number","nullable":true}},"required":["request_id","ok","action"]}}}}}}},"/v0/usage":{"get":{"description":"Current usage and estimated charges","summary":"Usage","tags":["Billing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"period":{"type":"string"},"usage":{"type":"object","properties":{"computer_runtime_seconds":{"type":"number"},"browser_runtime_seconds":{"type":"number"},"search_count":{"type":"number"},"answer_count":{"type":"number"}},"required":["computer_runtime_seconds","browser_runtime_seconds","search_count","answer_count"]},"costs":{"type":"object","properties":{"underlying_cost_usd":{"type":"number"},"markup_multiplier":{"type":"number"},"estimated_charge_usd":{"type":"number"}},"required":["underlying_cost_usd","markup_multiplier","estimated_charge_usd"]},"active_sessions":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"type":{"type":"string","enum":["browser","computer"]},"runtime_seconds":{"type":"number"},"estimated_cost_usd":{"type":"number"}},"required":["session_id","type","runtime_seconds","estimated_cost_usd"]}},"spending_limit_usd":{"type":"number","nullable":true},"spending_limit_remaining_usd":{"type":"number","nullable":true},"billing_status":{"type":"string"},"zdr_enabled":{"type":"boolean"}},"required":["request_id","period","usage","costs","active_sessions","spending_limit_usd","spending_limit_remaining_usd","billing_status"]}}}}}}},"/v0/browser/sessions":{"post":{"description":"Create a browser Fly Sprite session","summary":"Create browser session","tags":["Sessions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"session_id":{"type":"string"},"session_secret":{"type":"string"},"status":{"type":"string","enum":["starting","ready","active","destroyed","failed"]},"type":{"type":"string","enum":["browser","computer"]},"capabilities":{"type":"array","items":{"type":"string","enum":["browser","computer","terminal","files","screenshots"]}},"created_at":{"type":"number"},"expires_at":{"type":"number"},"zdr":{"type":"boolean"}},"required":["request_id","session_id","session_secret","status","type","capabilities","created_at","expires_at"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"502":{"description":"Sprite provisioning failed","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/browser/sessions/{id}":{"post":{"description":"Proxy a daemon command to a browser session","summary":"browser session command","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","minLength":1},"args":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"session":{"type":"string","default":"default"},"timeout_ms":{"type":"integer","minimum":0,"exclusiveMinimum":true},"zdr":{"type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"Command result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"ok":{"type":"boolean"},"action":{"type":"string"},"data":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"error_kind":{"type":"string","nullable":true},"elapsed_ms":{"type":"number","nullable":true}},"required":["request_id","ok","action"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}},"delete":{"description":"Destroy a browser session and release its Sprite","summary":"Delete browser session","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session deleted","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"session_id":{"type":"string"}},"required":["request_id","deleted","session_id"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/computer/sessions":{"post":{"description":"Create a computer Fly Sprite session","summary":"Create computer session","tags":["Sessions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"session_id":{"type":"string"},"session_secret":{"type":"string"},"status":{"type":"string","enum":["starting","ready","active","destroyed","failed"]},"type":{"type":"string","enum":["browser","computer"]},"capabilities":{"type":"array","items":{"type":"string","enum":["browser","computer","terminal","files","screenshots"]}},"created_at":{"type":"number"},"expires_at":{"type":"number"},"zdr":{"type":"boolean"}},"required":["request_id","session_id","session_secret","status","type","capabilities","created_at","expires_at"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"502":{"description":"Sprite provisioning failed","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/computer/sessions/{id}":{"post":{"description":"Proxy a daemon command to a computer session","summary":"computer session command","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","minLength":1},"args":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"session":{"type":"string","default":"default"},"timeout_ms":{"type":"integer","minimum":0,"exclusiveMinimum":true},"zdr":{"type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"Command result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"ok":{"type":"boolean"},"action":{"type":"string"},"data":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"error_kind":{"type":"string","nullable":true},"elapsed_ms":{"type":"number","nullable":true}},"required":["request_id","ok","action"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}},"delete":{"description":"Destroy a computer session and release its Sprite","summary":"Delete computer session","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session deleted","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"session_id":{"type":"string"}},"required":["request_id","deleted","session_id"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}},"/v0/sessions/{id}/files":{"post":{"description":"Upload a file to a session Sprite","summary":"Upload session file","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Uploaded file metadata","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"path":{"type":"string"},"size_bytes":{"type":"number"}},"required":["request_id","path","size_bytes"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}},"get":{"description":"Download a file from a session Sprite","summary":"Download session file","tags":["Sessions"],"security":[{"bearerAuth":[],"sessionSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"File bytes or base64 JSON","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"path":{"type":"string"},"size_bytes":{"type":"number"},"mime_type":{"type":"string"},"data_base64":{"type":"string"},"image_url":{"type":"string"}},"required":["request_id","path","size_bytes","mime_type"]}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Session or file not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","message"]}},"required":["request_id","error"]}}}}}}}}}