{"openapi":"3.0.0","info":{"title":"TinyFish Browser API","version":"1.0.0","description":"Create remote browser sessions for direct Playwright/CDP control.","contact":{"name":"TinyFish Support","email":"support@tinyfish.ai"}},"servers":[{"url":"https://api.browser.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":{"/":{"post":{"operationId":"createBrowserSession","summary":"Create a remote browser session","description":"Creates a remote tf-browser session and returns CDP connection details. Connect to the browser via CDP WebSocket at `cdp_url`.\n\nBy default the session egresses through the TinyFish residential proxy in the US, pinned to one exit IP for the life of the session. Use `proxy_config` to pick another country (`country_code`, any ISO 3166-1 alpha-2), bring your own proxy (`type: \"custom\"`), or disable the proxy (`enabled: false`).\n\nUse `timeout_seconds` to set a custom inactivity timeout (5–86400 seconds). If omitted, null, or greater than your plan maximum, the plan maximum is used (15 min on free tier, 60 min on paid).","security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Browser session parameters","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Target URL the browser session will navigate to on startup. Bare domains (e.g. tinyfish.ai) are automatically prefixed with https://. If omitted, the browser starts at about:blank.","example":"https://www.tinyfish.ai"},"timeout_seconds":{"type":"integer","nullable":true,"minimum":5,"maximum":86400,"description":"Inactivity timeout in seconds (5–86400). If omitted, null, or greater than your plan maximum, the plan maximum is used.","example":300},"proxy_config":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"Route the session through a proxy. false means direct egress.","example":true},"type":{"type":"string","enum":["tinyfish","custom"],"default":"tinyfish","description":"\"tinyfish\" uses the TinyFish residential proxy, pinned to one exit IP per session. \"custom\" routes through your own proxy — requires url.","example":"tinyfish"},"country_code":{"type":"string","description":"Exit country for the TinyFish proxy (ISO 3166-1 alpha-2). Defaults to US.","example":"US"},"url":{"type":"string","format":"uri","description":"Your HTTP or HTTPS proxy server URL. Required when type is \"custom\".","example":"http://proxy.example.com:8080"},"username":{"type":"string","description":"Username for the custom proxy."},"password":{"type":"string","description":"Password for the custom proxy."}},"additionalProperties":false,"description":"Proxy for the session. Omit to use the TinyFish proxy in the US."}},"description":"Browser session creation parameters"}}}},"responses":{"201":{"description":"Browser session created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","minLength":1,"description":"Unique identifier for this browser session.","example":"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"cdp_url":{"type":"string","format":"uri","description":"WebSocket URL for browser connection. Pass this to Playwright's connect_over_cdp or any WebSocket-based CDP client.","example":"wss://browser.example.tinyfish.io/session/cdp"},"base_url":{"type":"string","format":"uri","description":"HTTPS base URL for the session. Use to access session endpoints such as /pages.","example":"https://browser.example.tinyfish.io/session"}},"required":["session_id","cdp_url","base_url"],"description":"Browser session created successfully. Connect to the browser via cdp_url."},"example":{"session_id":"tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890","cdp_url":"wss://tetra-abc123.cluster.unikraft.cloud/cdp","base_url":"https://tetra-abc123.cluster.unikraft.cloud"}}}},"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":"Forbidden - Insufficient credits or no active subscription","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":"Browser 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"}}}},"409":{"description":"Upstream conflict creating the session — retry shortly (RETRY_REQUIRED)","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 limited by browser infrastructure (RATE_LIMIT_EXCEEDED) — honor Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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, including non-retryable upstream failures","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":"Browser infrastructure temporarily unavailable (SERVICE_BUSY) — retryable, honor Retry-After; error.details.upstream_status carries the observed upstream status","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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"}}}},"504":{"description":"Browser infrastructure timed out creating the session (TIMEOUT)","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":"listBrowserUsage","summary":"List browser session usage","description":"List Tetra browser session usage for the authenticated user. Returns session telemetry including duration, data transfer, mode, and status.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"session_id","in":"query"},{"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":["running","ended"]},"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":"Browser usage retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"user_id":{"type":"string"},"sub_user_id":{"type":"string","nullable":true},"mode":{"type":"string","enum":["light","stealth","tf-browser"]},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","nullable":true,"format":"date-time"},"duration_ms":{"type":"integer","nullable":true},"proxy_trg_rx_bytes":{"type":"integer","nullable":true},"proxy_trg_tx_bytes":{"type":"integer","nullable":true},"status":{"type":"string","enum":["running","ended","created"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["session_id","user_id","sub_user_id","mode","start_time","end_time","duration_ms","proxy_trg_rx_bytes","proxy_trg_tx_bytes","status","created_at","updated_at"],"description":"A single browser 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 browser usage response"},"example":{"items":[{"session_id":"tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890","user_id":"cus_abc123","sub_user_id":"user_abc123","mode":"tf-browser","start_time":"2026-03-18T16:18:35Z","end_time":"2026-03-18T16:28:36Z","duration_ms":600543,"proxy_trg_rx_bytes":38006,"proxy_trg_tx_bytes":952337,"status":"ended","created_at":"2026-03-18T16:18:12Z","updated_at":"2026-03-18T16:28:36Z"}],"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":"Browser 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"}}}},"409":{"description":"Upstream conflict fetching usage (RETRY_REQUIRED) — retry shortly","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 limited by browser infrastructure (RATE_LIMIT_EXCEEDED) — honor Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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, including non-retryable upstream failures","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":"Browser infrastructure temporarily unavailable (SERVICE_BUSY) — retryable, honor Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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"}}}},"504":{"description":"Browser infrastructure timed out fetching usage (TIMEOUT) — retry","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"}}}}}}},"/{sessionId}":{"delete":{"operationId":"deleteBrowserSession","summary":"Terminate a browser session","description":"Terminates a remote browser session immediately. If the session is already ended this call is idempotent and still returns 204.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Session ID to terminate."},"required":true,"description":"Session ID to terminate.","name":"sessionId","in":"path"}],"responses":{"204":{"description":"Session terminated (or already ended)."},"400":{"description":"Invalid session ID","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":"Session not found or does not belong to the authenticated user","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"}}}},"409":{"description":"Conflicting operation on the session (RETRY_REQUIRED) — termination not confirmed, retry the delete shortly","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 limited by browser infrastructure (RATE_LIMIT_EXCEEDED) — honor Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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, including non-retryable upstream failures; the session may still be running — retry the delete","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":"Browser infrastructure temporarily unavailable (SERVICE_BUSY) — termination not confirmed, retry; honor Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"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"}}}},"504":{"description":"Browser infrastructure timed out terminating the session (TIMEOUT) — retry","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"}}}}}}}}}