{"openapi":"3.1.0","info":{"title":"CrawlGenie API","version":"0.2.0","description":"Self-hosted browser infrastructure for AI agents: governed sessions, agent-native snapshots, approvals, recorder/rewind, profiles, routines, proxies."},"servers":[{"url":"https://crawlgenie.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CreateSession":{"type":"object","properties":{"tier":{"default":"shared","type":"string","enum":["shared","isolated"]},"profile":{"type":"string"},"persistProfile":{"default":true,"type":"boolean"},"profileLock":{"default":"exclusive","type":"string","enum":["exclusive","shared"]},"viewport":{"default":{"width":1280,"height":800},"type":"object","properties":{"width":{"default":1280,"type":"integer","minimum":320,"maximum":3840},"height":{"default":800,"type":"integer","minimum":240,"maximum":2160}}},"userAgent":{"type":"string"},"locale":{"default":"en-US","type":"string"},"timezoneId":{"type":"string"},"proxy":{"anyOf":[{"type":"object","properties":{"server":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"bypass":{"type":"string"}},"required":["server"]},{"type":"object","properties":{"pool":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"sticky":{"type":"string"}}}]},"stealth":{"default":true,"type":"boolean"},"url":{"type":"string","minLength":1},"policy":{"default":{},"type":"object","properties":{"allowDomains":{"type":"array","items":{"type":"string"}},"blockDomains":{"type":"array","items":{"type":"string"}},"blockResources":{"default":[],"type":"array","items":{"type":"string","enum":["document","stylesheet","image","media","font","script","texttrack","xhr","fetch","eventsource","websocket","manifest","other"]}},"blockTrackers":{"default":true,"type":"boolean"},"allowPrivateNetwork":{"default":false,"type":"boolean"},"strictNetwork":{"default":false,"type":"boolean"},"signedAgent":{"type":"boolean"},"maxDurationSec":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"idleTimeoutSec":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maxPages":{"default":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maxActions":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maxBytes":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"approvals":{"default":{"mode":"off","patterns":[],"timeoutSec":300},"type":"object","properties":{"mode":{"default":"off","type":"string","enum":["off","destructive","all"]},"patterns":{"default":[],"type":"array","items":{"type":"string"}},"timeoutSec":{"default":300,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"record":{"default":true,"type":"boolean"}}},"snapshotDefaults":{"default":{"mode":"interactive","maxChars":12000,"delta":false},"type":"object","properties":{"mode":{"default":"interactive","type":"string","enum":["interactive","full"]},"maxChars":{"default":12000,"type":"integer","minimum":500,"maximum":200000},"delta":{"default":false,"type":"boolean"}}},"extensions":{"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9._-]+$"}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"ActRequest":{"type":"object","properties":{"actions":{"minItems":1,"maxItems":25,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"goto"},"url":{"type":"string","minLength":1},"waitUntil":{"default":"domcontentloaded","type":"string","enum":["load","domcontentloaded","networkidle","commit"]}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","const":"back"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"forward"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"reload"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"click"},"ref":{"type":"string"},"button":{"default":"left","type":"string","enum":["left","right","middle"]},"clickCount":{"default":1,"type":"integer","minimum":1,"maximum":3}},"required":["type","ref"]},{"type":"object","properties":{"type":{"type":"string","const":"dblclick"},"ref":{"type":"string"}},"required":["type","ref"]},{"type":"object","properties":{"type":{"type":"string","const":"hover"},"ref":{"type":"string"}},"required":["type","ref"]},{"type":"object","properties":{"type":{"type":"string","const":"fill"},"ref":{"type":"string"},"text":{"type":"string"}},"required":["type","ref","text"]},{"type":"object","properties":{"type":{"type":"string","const":"type"},"ref":{"type":"string"},"text":{"type":"string"},"delayMs":{"default":0,"type":"integer","minimum":0,"maximum":500}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string"},"ref":{"type":"string"}},"required":["type","key"]},{"type":"object","properties":{"type":{"type":"string","const":"select"},"ref":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["type","ref","values"]},{"type":"object","properties":{"type":{"type":"string","const":"check"},"ref":{"type":"string"},"checked":{"default":true,"type":"boolean"}},"required":["type","ref"]},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"ref":{"type":"string"},"deltaX":{"default":0,"type":"number"},"deltaY":{"default":600,"type":"number"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"upload"},"ref":{"type":"string"},"files":{"minItems":1,"type":"array","items":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"mimeType":{"type":"string"},"base64":{"type":"string"}},"required":["name","mimeType","base64"]},{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}]}}},"required":["type","ref","files"]},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"ms":{"type":"integer","minimum":0,"maximum":30000},"text":{"type":"string"},"selector":{"type":"string"},"url":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"assert"},"text":{"type":"string"},"notText":{"type":"string"},"selector":{"type":"string"},"url":{"type":"string"},"title":{"type":"string"},"timeoutMs":{"default":5000,"type":"integer","minimum":0,"maximum":30000}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"evaluate"},"expression":{"type":"string"}},"required":["type","expression"]},{"type":"object","properties":{"type":{"type":"string","const":"dialog"},"accept":{"default":true,"type":"boolean"},"promptText":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"tab"},"action":{"type":"string","enum":["new","switch","close","list"]},"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"url":{"type":"string"}},"required":["type","action"]}]}},"snapshot":{"default":true,"type":"boolean"},"snapshotOptions":{"type":"object","properties":{"mode":{"default":"interactive","type":"string","enum":["interactive","full"]},"maxChars":{"default":12000,"type":"integer","minimum":500,"maximum":200000},"delta":{"default":false,"type":"boolean"}}}},"required":["actions"]},"SnapshotOptions":{"type":"object","properties":{"mode":{"default":"interactive","type":"string","enum":["interactive","full"]},"maxChars":{"default":12000,"type":"integer","minimum":500,"maximum":200000},"delta":{"default":false,"type":"boolean"}}},"SessionInfo":{"type":"object","description":"See docs/API.md#sessions","additionalProperties":true},"ActResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true}},"snapshot":{"type":"object","additionalProperties":true}}}}},"security":[{"bearerAuth":[]}],"paths":{"/healthz":{"get":{"security":[],"summary":"Liveness","responses":{"200":{"description":"ok"}}}},"/v1/stats":{"get":{"summary":"Capacity, pool and memory stats","responses":{"200":{"description":"stats"}}}},"/v1/sessions":{"get":{"summary":"List sessions","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["running","all"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SessionInfo"}}}}}}},"post":{"summary":"Create a session","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSession"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInfo"}}}},"409":{"description":"profile_locked"},"429":{"description":"capacity"}}}},"/v1/sessions/{id}":{"get":{"summary":"Session info (running or closed)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInfo"}}}},"404":{"description":"not found"}}},"delete":{"summary":"Close a session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInfo"}}}}}}},"/v1/sessions/{id}/navigate":{"post":{"summary":"Navigate (goto) and snapshot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"waitUntil":{"type":"string","enum":["load","domcontentloaded","networkidle","commit"]},"snapshot":{"type":"boolean"}}}}}},"responses":{"200":{"description":"result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActResult"}}}}}}},"/v1/sessions/{id}/snapshot":{"get":{"summary":"Accessibility snapshot with refs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mode","in":"query","schema":{"type":"string","enum":["interactive","full"]}},{"name":"maxChars","in":"query","schema":{"type":"integer"}},{"name":"delta","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"snapshot"}}}},"/v1/sessions/{id}/act":{"post":{"summary":"Run a batch of actions by ref","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActRequest"}}}},"responses":{"200":{"description":"result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActResult"}}}}}}},"/v1/sessions/{id}/screenshot":{"get":{"summary":"Screenshot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["png","jpeg"]}},{"name":"fullPage","in":"query","schema":{"type":"boolean"}},{"name":"quality","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"image","content":{"image/jpeg":{},"image/png":{}}}}}},"/v1/sessions/{id}/text":{"get":{"summary":"Reader-mode text","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"maxChars","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"text"}}}},"/v1/sessions/{id}/links":{"get":{"summary":"Links with text","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"links"}}}},"/v1/sessions/{id}/pdf":{"get":{"summary":"PDF of the page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"pdf","content":{"application/pdf":{}}}}}},"/v1/sessions/{id}/profile":{"post":{"summary":"Save cookies/localStorage as a named profile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"200":{"description":"saved"}}}},"/v1/sessions/{id}/events":{"get":{"summary":"Recorded events","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"events"}}}},"/v1/sessions/{id}/events/stream":{"get":{"summary":"Server-sent events stream","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/sessions/{id}/events/{seq}/screenshot":{"get":{"summary":"Screenshot recorded at a step","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"seq","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"image/jpeg"},"404":{"description":"no screenshot"}}}},"/v1/sessions/{id}/fork":{"post":{"summary":"New session from the state recorded at a step (rewind)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seq"],"properties":{"seq":{"type":"integer"},"tier":{"type":"string","enum":["shared","isolated"]}}}}}},"responses":{"201":{"description":"forked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInfo"}}}}}}},"/v1/sessions/{id}/approvals":{"get":{"summary":"Pending approvals for a session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"approvals"}}}},"/v1/sessions/{id}/approvals/{aid}":{"post":{"summary":"Approve or deny a held action","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"aid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["approved"],"properties":{"approved":{"type":"boolean"},"by":{"type":"string"}}}}}},"responses":{"200":{"description":"ok"}}}},"/v1/approvals":{"get":{"summary":"All pending approvals","responses":{"200":{"description":"approvals"}}}},"/v1/profiles":{"get":{"summary":"Saved profiles","responses":{"200":{"description":"profiles"}}}},"/v1/profiles/{name}":{"delete":{"summary":"Delete a profile","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"}}}},"/v1/routines":{"get":{"summary":"List routines","responses":{"200":{"description":"routines"}}},"post":{"summary":"Create a routine from a session recording","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sessionId"],"properties":{"name":{"type":"string"},"sessionId":{"type":"string"},"fromSeq":{"type":"integer"},"toSeq":{"type":"integer"},"params":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"routine"}}}},"/v1/routines/{name}":{"get":{"summary":"Routine detail","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"routine"}}},"put":{"summary":"Update description/params/steps","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"routine"}}},"delete":{"summary":"Delete a routine","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"}}}},"/v1/routines/{name}/run":{"post":{"summary":"Replay a routine with self-healing lookup","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}},"session":{"$ref":"#/components/schemas/CreateSession"},"closeAfter":{"type":"boolean"}}}}}},"responses":{"200":{"description":"run result"}}}},"/v1/proxies":{"get":{"summary":"Proxy pools and endpoint health (no credentials)","responses":{"200":{"description":"pools"}}}},"/v1/tools":{"get":{"summary":"Tool definitions for function calling","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["openai","anthropic","gemini","json"]}}],"responses":{"200":{"description":"tools"}}}},"/v1/tools/{name}":{"post":{"summary":"Call a tool","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-vessel-agent","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"tool result"}}}},"/v1/admin/prune":{"post":{"summary":"Delete old closed sessions now","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"olderThanDays":{"type":"number"}}}}}},"responses":{"200":{"description":"count"}}}},"/v1/secrets":{"get":{"summary":"Vault secrets (names + metadata, never values)","responses":{"200":{"description":"secrets"}}}},"/v1/secrets/{name}":{"put":{"summary":"Store or update a secret; agents use it as {{secret:name}} in fill/type. Store an authenticator seed (base32 or otpauth:// URL) and use {{totp:name}} to type the current one-time code","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"meta"}}},"delete":{"summary":"Delete a secret","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"}}}},"/v1/sessions/{id}/files":{"post":{"summary":"Upload a file (application/octet-stream) for use in upload actions by id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"file"}}},"get":{"summary":"Files uploaded to this session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"files"}}}},"/v1/scrape":{"post":{"summary":"One-shot: open a URL (or parse a PDF/DOCX), extract, close; q = question-focused passages","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"format":{"type":"string","enum":["markdown","text","html","snapshot","links"]},"q":{"type":"string"},"focusChars":{"type":"integer"},"maxTokens":{"type":"integer"},"actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"changeTracking":{"type":"boolean"},"waitFor":{"type":"string"},"waitMs":{"type":"integer"},"maxChars":{"type":"integer"},"screenshot":{"type":"boolean"},"pdf":{"type":"boolean"},"session":{"$ref":"#/components/schemas/CreateSession"}}}}}},"responses":{"200":{"description":"content"}}}},"/v1/parse":{"post":{"summary":"Parse a PDF / DOCX / text document to text (no browser)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"base64":{"type":"string"},"filename":{"type":"string"},"maxChars":{"type":"integer"},"q":{"type":"string"}}}}}},"responses":{"200":{"description":"content"}}}},"/v1/extractors":{"get":{"summary":"Extractor catalogue grouped by vertical","responses":{"200":{"description":"extractors"}}}},"/v1/extractors/{id}/run":{"post":{"summary":"Run an extractor once and return rows (sync); ?format=csv","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","additionalProperties":true},"session":{"$ref":"#/components/schemas/CreateSession"}}}}}},"responses":{"200":{"description":"rows"}}}},"/v1/watches/{id}/dataset":{"get":{"summary":"All rows ever seen by a watch, merged across runs (first/last seen)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}},{"name":"since","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"rows"}}}},"/v1/screenshot":{"get":{"summary":"One-shot screenshot of a URL","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"fullPage","in":"query","schema":{"type":"boolean"}},{"name":"type","in":"query","schema":{"type":"string","enum":["png","jpeg"]}},{"name":"waitMs","in":"query","schema":{"type":"integer"}},{"name":"proxyPool","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"image","content":{"image/jpeg":{},"image/png":{}}}}}},"/v1/pdf":{"get":{"summary":"One-shot PDF of a URL","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"waitMs","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"pdf","content":{"application/pdf":{}}}}}},"/auth/me":{"get":{"summary":"Who am I (cloud mode); public","responses":{"200":{"description":"me"}}}},"/auth/signup":{"post":{"summary":"Create a workspace (VESSEL_SIGNUP=true); sets the vessel_sid cookie","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"},"org":{"type":"string"}}}}}},"responses":{"201":{"description":"user + org"}}}},"/auth/login":{"post":{"summary":"Sign in; sets the vessel_sid cookie","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"user + org"}}}},"/auth/logout":{"post":{"summary":"Clear the cookie","responses":{"200":{"description":"ok"}}}},"/v1/keys":{"get":{"summary":"API keys of the caller's organisation","responses":{"200":{"description":"keys"}}},"post":{"summary":"Mint an API key (returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"key"}}}},"/v1/keys/{id}":{"delete":{"summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"revoked"}}}},"/v1/sessions/{id}/script":{"post":{"summary":"Run a Playwright snippet on the node (VESSEL_ALLOW_SCRIPTS)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"timeoutMs":{"type":"integer"}}}}}},"responses":{"200":{"description":"value + logs"}}}},"/v1/playbooks":{"get":{"summary":"Built-in agents catalogue (no model key)","responses":{"200":{"description":"playbooks"}}}},"/v1/watches":{"get":{"summary":"Configured watches","responses":{"200":{"description":"watches"}}},"post":{"summary":"Create a watch (built-in agent instance)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","input"],"properties":{"kind":{"type":"string"},"input":{"type":"object","additionalProperties":true},"name":{"type":"string"},"cron":{"type":["string","null"]},"timezone":{"type":"string"},"webhookUrl":{"type":"string"},"notifyOnlyOnChange":{"type":"boolean"},"runNow":{"type":"boolean"},"session":{"$ref":"#/components/schemas/CreateSession"}}}}}},"responses":{"201":{"description":"watch"}}}},"/v1/watches/{id}":{"get":{"summary":"Watch + recent runs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"watch"}}},"put":{"summary":"Update a watch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"watch"}}},"delete":{"summary":"Delete a watch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"}}}},"/v1/watches/{id}/run":{"post":{"summary":"Run a watch now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"run"}}}},"/v1/watches/{id}/runs/{runId}/export":{"get":{"summary":"Export an extractor run as CSV or JSON","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"]}},{"name":"only","in":"query","schema":{"type":"string","enum":["all","new"]}}],"responses":{"200":{"description":"text/csv or application/json attachment"}}}},"/v1/agent/run":{"post":{"summary":"Run a natural-language task with your model key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string"},"url":{"type":"string"},"sessionId":{"type":"string"},"maxSteps":{"type":"integer"},"keepSession":{"type":"boolean"},"session":{"$ref":"#/components/schemas/CreateSession"}}}}}},"responses":{"202":{"description":"run"}}}},"/v1/agent/runs/{id}":{"get":{"summary":"Agent run status, steps, usage, result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"run"}}},"delete":{"summary":"Stop a run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cancelled"}}}},"/v1/schedules":{"get":{"summary":"Cron schedules for routines","responses":{"200":{"description":"schedules"}}},"post":{"summary":"Create a schedule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","routine","cron"],"properties":{"name":{"type":"string"},"routine":{"type":"string"},"cron":{"type":"string"},"timezone":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}},"webhookUrl":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"201":{"description":"schedule"}}}},"/v1/schedules/{id}/run":{"post":{"summary":"Run a schedule now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"run"}}}},"/v1/crawl":{"get":{"summary":"Crawl jobs","responses":{"200":{"description":"jobs"}}},"post":{"summary":"Crawl a site into markdown (async job)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"limit":{"type":"integer"},"maxDepth":{"type":"integer"},"includePaths":{"type":"array","items":{"type":"string"}},"excludePaths":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string","enum":["markdown","links","html","text"]}},"concurrency":{"type":"integer"},"respectRobots":{"type":"boolean"}}}}}},"responses":{"202":{"description":"job"}}}},"/v1/crawl/{id}":{"get":{"summary":"Crawl job status + pages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"content","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"job"}}},"delete":{"summary":"Cancel + delete a crawl job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"}}}},"/v1/batch-scrape":{"post":{"summary":"Scrape a list of URLs (async job)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"202":{"description":"job"}}}},"/v1/map":{"post":{"summary":"Discover a site’s URLs (sitemaps + links)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"limit":{"type":"integer"},"includeSubdomains":{"type":"boolean"},"search":{"type":"string"}}}}}},"responses":{"200":{"description":"urls"}}}},"/v1/extract":{"post":{"summary":"Prompt + JSON schema → structured data with your model key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"url":{"type":"string"},"urls":{"type":"array","items":{"type":"string"}},"prompt":{"type":"string"},"schema":{"type":"object","additionalProperties":true},"perPage":{"type":"boolean"}}}}}},"responses":{"200":{"description":"data"}}}},"/v1/search":{"get":{"summary":"Web search through the browser (no API key); content=true attaches markdown of the top hits","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"max","in":"query","schema":{"type":"integer"}},{"name":"content","in":"query","schema":{"type":"boolean"}},{"name":"contentMax","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"hits"}}}},"/v1/stats/savings":{"get":{"summary":"Measured token savings (read vs full tree vs HTML)","parameters":[{"name":"days","in":"query","schema":{"type":"integer"}},{"name":"price","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"savings"}}}},"/v1/measure":{"post":{"summary":"Exact token counts for one page, three ways","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}}}},"responses":{"200":{"description":"tokens"}}}},"/v1/members":{"get":{"summary":"Workspace members + open invite links","responses":{"200":{"description":"members"}}}},"/v1/invites":{"post":{"summary":"Create an invite link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"maxUses":{"type":"integer"},"ttlDays":{"type":"integer"},"role":{"type":"string","enum":["member","owner"]}}}}}},"responses":{"201":{"description":"invite"}}}},"/v1/billing":{"get":{"summary":"Plan, usage and upgrade links for the caller’s workspace","responses":{"200":{"description":"billing"}}}},"/v1/admin/backups":{"get":{"summary":"Backup status + objects (admin)","responses":{"200":{"description":"backups"}}}},"/mcp":{"post":{"summary":"MCP endpoint (Streamable HTTP, spec 2026-07-28; 2025 clients served statelessly)","responses":{"200":{"description":"mcp"}}}}}}