{"openapi":"3.0.0","info":{"title":"TinyFish Web Agent Automation API","version":"1.0.0","description":"REST API for running AI-powered browser automations. Execute tasks on any website using natural language instructions.","contact":{"name":"TinyFish Support","email":"support@tinyfish.ai"}},"servers":[{"url":"https://agent.tinyfish.ai","description":"Production"}],"tags":[{"name":"Automation","description":"Browser automation endpoints for executing tasks on websites"},{"name":"Runs","description":"Endpoints for retrieving automation run data"},{"name":"Browser","description":"Remote browser session endpoints"},{"name":"Fetch","description":"Fetch URLs and extract clean page content"},{"name":"Search","description":"Web search endpoints"},{"name":"Browser Context Profiles","description":"Saved browser context endpoints for managing reusable login state, cookies, storage, and profile setup sessions"},{"name":"Vault","description":"Vault credential management endpoints for connecting password managers and managing stored credentials"},{"name":"Research","description":"Source-backed research report endpoints"},{"name":"Wallet","description":"Wallet balance, auto-reload, rates, and top-up endpoints"}],"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":{"/v1/automation/run-sse":{"post":{"operationId":"runSse","description":"Execute a browser automation task with Server-Sent Events (SSE) streaming. Returns a real-time event stream with automation progress, browser streaming URL, and final results.","summary":"Run browser automation with SSE streaming","tags":["Automation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Automation task parameters","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Target website URL to automate","example":"https://example.com"},"goal":{"type":"string","minLength":1,"description":"Natural language description of what to accomplish on the website","example":"Find the pricing page and extract all plan details"},"browser_profile":{"type":"string","enum":["lite","stealth"],"description":"Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.","example":"lite"},"api_integration":{"type":"string","description":"Name of the integration making this API call (e.g., \"dify\", \"zapier\", \"n8n\"). Used for analytics.","example":"dify"},"agent_config":{"type":"object","properties":{"mode":{"type":"string","enum":["default","strict"],"description":"Agent behavior mode. \"strict\" enables fail-fast for test automation.","example":"strict"},"cursor_style":{"type":"string","enum":["fish","standard","green-pointer"],"description":"Cursor style for the browser agent.","example":"standard"},"max_steps":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum tool-call steps before the agent stops. Defaults to 150.","example":50},"max_duration_seconds":{"type":"integer","minimum":1,"description":"Maximum wall-clock seconds before the agent stops. Defaults to no limit.","example":300}},"description":"Agent behavior configuration","additionalProperties":false},"capture_config":{"type":"object","properties":{"elements":{"type":"boolean"},"snapshots":{"type":"boolean"},"screenshots":{"type":"boolean"},"recording":{"type":"boolean"},"html":{"type":"boolean"}},"description":"Configure which data to capture during the run.","additionalProperties":false},"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS."},"use_vault":{"type":"boolean","description":"Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.","example":true},"use_profile":{"type":"boolean","description":"Opt-in to the default Browser Context Profile if Browser Context Profiles are enabled; legacy callers are silently ignored when the profiles feature is disabled. Returns 400 when enabled but no default profile is set.","example":true},"profile_id":{"type":"string","minLength":1,"description":"Browser Context Profile ID to use when use_profile is true.","example":"prof_abc123def4567890"},"credential_item_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.","example":["cred:conn-abc:Work:item-123","cred:conn-def:Personal:item-456"]},"proxy_config":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable proxy for this automation run","example":true},"country_code":{"type":"string","enum":["US","GB","CA","DE","FR","JP","AU"],"description":"Country code for proxy location.","example":"US"}},"required":["enabled"],"description":"Proxy configuration","additionalProperties":false},"output_schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true},"description":"Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}}},"required":["url","goal"]}}}},"responses":{"200":{"description":"Server-Sent Events stream. Stream sends STARTED, STREAMING_URL (optional), PROGRESS (intermediate events with purpose), COMPLETE events, plus periodic HEARTBEAT messages.","content":{"text/event-stream":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STARTED"]},"run_id":{"type":"string"},"timestamp":{"type":"string"}},"required":["type","run_id","timestamp"]},{"type":"object","properties":{"type":{"type":"string","enum":["STREAMING_URL"]},"run_id":{"type":"string"},"streaming_url":{"type":"string"},"timestamp":{"type":"string"}},"required":["type","run_id","streaming_url","timestamp"]},{"type":"object","properties":{"type":{"type":"string","enum":["COMPLETE"]},"run_id":{"type":"string"},"status":{"type":"string","enum":["COMPLETED","FAILED","CANCELLED"]},"error":{"type":"string"},"help_url":{"type":"string"},"help_message":{"type":"string"},"profile_hint":{"type":"object","properties":{"message":{"type":"string"},"setup_url":{"type":"string"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"]}},"required":["message","setup_url","reason"]},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"timestamp":{"type":"string"}},"required":["type","run_id","status","timestamp"]},{"type":"object","properties":{"type":{"type":"string","enum":["HEARTBEAT"]},"timestamp":{"type":"string"}},"required":["type","timestamp"]},{"type":"object","properties":{"type":{"type":"string","enum":["PROGRESS"]},"run_id":{"type":"string"},"purpose":{"type":"string"},"tinyfish_api":{"type":"string","enum":["search","fetch"]},"timestamp":{"type":"string"}},"required":["type","run_id","purpose","timestamp"]},{"type":"object","properties":{"type":{"type":"string","enum":["TF_API_RESULT"]},"run_id":{"type":"string"},"tinyfish_api":{"type":"string","enum":["search","fetch"]},"result":{"type":"array","items":{"nullable":true}},"timestamp":{"type":"string"}},"required":["type","run_id","tinyfish_api","result","timestamp"]}]},"example":"data: {\"type\":\"STARTED\",\"run_id\":\"run_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}\n\ndata: {\"type\":\"STREAMING_URL\",\"run_id\":\"run_123\",\"streaming_url\":\"https://...\",\"timestamp\":\"...\"}\n\ndata: {\"type\":\"PROGRESS\",\"run_id\":\"run_123\",\"purpose\":\"Clicking submit button\",\"timestamp\":\"...\"}\n\ndata: {\"type\":\"COMPLETE\",\"run_id\":\"run_123\",\"status\":\"COMPLETED\",\"result\":{...},\"timestamp\":\"...\"}"}}},"400":{"description":"Invalid request - missing required fields or invalid format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required - wallet balance too low to start this run","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/automation/run":{"post":{"operationId":"run","description":"Execute a browser automation task synchronously and wait for completion. Returns the final result once the automation finishes (success or failure). Use this endpoint when you need the complete result in a single response. Note: Runs created via this endpoint cannot be cancelled. If you need cancellation support, use `/v1/automation/run-async` or `/v1/automation/run-sse` instead.","summary":"Run browser automation synchronously","tags":["Automation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Automation task parameters","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Target website URL to automate","example":"https://example.com"},"goal":{"type":"string","minLength":1,"description":"Natural language description of what to accomplish on the website","example":"Find the pricing page and extract all plan details"},"browser_profile":{"type":"string","enum":["lite","stealth"],"description":"Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.","example":"lite"},"api_integration":{"type":"string","description":"Name of the integration making this API call (e.g., \"dify\", \"zapier\", \"n8n\"). Used for analytics.","example":"dify"},"agent_config":{"type":"object","properties":{"mode":{"type":"string","enum":["default","strict"],"description":"Agent behavior mode. \"strict\" enables fail-fast for test automation.","example":"strict"},"cursor_style":{"type":"string","enum":["fish","standard","green-pointer"],"description":"Cursor style for the browser agent.","example":"standard"},"max_steps":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum tool-call steps before the agent stops. Defaults to 150.","example":50},"max_duration_seconds":{"type":"integer","minimum":1,"description":"Maximum wall-clock seconds before the agent stops. Defaults to no limit.","example":300}},"description":"Agent behavior configuration","additionalProperties":false},"capture_config":{"type":"object","properties":{"elements":{"type":"boolean"},"snapshots":{"type":"boolean"},"screenshots":{"type":"boolean"},"recording":{"type":"boolean"},"html":{"type":"boolean"}},"description":"Configure which data to capture during the run.","additionalProperties":false},"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS."},"use_vault":{"type":"boolean","description":"Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.","example":true},"use_profile":{"type":"boolean","description":"Opt-in to the default Browser Context Profile if Browser Context Profiles are enabled; legacy callers are silently ignored when the profiles feature is disabled. Returns 400 when enabled but no default profile is set.","example":true},"profile_id":{"type":"string","minLength":1,"description":"Browser Context Profile ID to use when use_profile is true.","example":"prof_abc123def4567890"},"credential_item_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.","example":["cred:conn-abc:Work:item-123","cred:conn-def:Personal:item-456"]},"proxy_config":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable proxy for this automation run","example":true},"country_code":{"type":"string","enum":["US","GB","CA","DE","FR","JP","AU"],"description":"Country code for proxy location.","example":"US"}},"required":["enabled"],"description":"Proxy configuration","additionalProperties":false},"output_schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true},"description":"Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}}},"required":["url","goal"]}}}},"responses":{"200":{"description":"Automation completed or failed after execution started. Returns run details.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","nullable":true,"description":"Unique identifier for the automation run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["COMPLETED","FAILED"],"description":"Final status of the automation run","example":"COMPLETED"},"started_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run started","example":"2024-01-01T00:00:00Z"},"finished_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run finished","example":"2024-01-01T00:00:30Z"},"num_of_steps":{"type":"number","nullable":true,"description":"Number of steps taken during the automation. Null while the run is still in progress.","example":5},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Structured JSON result extracted from the automation. Null if the run failed.","example":{"product":"iPhone 15","price":"$799"}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code for programmatic handling","example":"service_busy"},"message":{"type":"string","description":"Error message describing why the run failed","example":"Browser crashed during execution"},"category":{"type":"string","enum":["SYSTEM_FAILURE","AGENT_FAILURE","BILLING_FAILURE","UNKNOWN"],"description":"Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).","example":"SYSTEM_FAILURE"},"retry_after":{"type":"number","nullable":true,"description":"Suggested retry delay in seconds (null if not retryable)","example":60},"help_url":{"type":"string","description":"URL to documentation for troubleshooting","example":"https://docs.tinyfish.ai/prompting-guide"},"help_message":{"type":"string","description":"Human-readable help message with guidance","example":"Need help? Check out our goal prompting guide for tips and examples."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["message","category"],"description":"Error details. Null if the run succeeded."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["run_id","status","started_at","finished_at","num_of_steps","result","error"],"description":"Automation run response. Check status to determine success/failure. On success: result is populated, error is null. On failure: result is null, error contains message."},"example":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"COMPLETED","started_at":"2024-01-01T00:00:00Z","finished_at":"2024-01-01T00:00:30Z","num_of_steps":5,"result":{"product":"iPhone 15","price":"$799"},"error":null}}}},"400":{"description":"Invalid request - missing required fields or invalid format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required - wallet balance too low to start this run","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"403":{"description":"Forbidden - 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"}}}},"500":{"description":"Server error - Automation failed during execution or internal infrastructure error occurred. Returns run details with error. For infrastructure errors (before run creation), run_id will be null and timestamps will be null.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","nullable":true,"description":"Unique identifier for the automation run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["COMPLETED","FAILED"],"description":"Final status of the automation run","example":"COMPLETED"},"started_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run started","example":"2024-01-01T00:00:00Z"},"finished_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run finished","example":"2024-01-01T00:00:30Z"},"num_of_steps":{"type":"number","nullable":true,"description":"Number of steps taken during the automation. Null while the run is still in progress.","example":5},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Structured JSON result extracted from the automation. Null if the run failed.","example":{"product":"iPhone 15","price":"$799"}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code for programmatic handling","example":"service_busy"},"message":{"type":"string","description":"Error message describing why the run failed","example":"Browser crashed during execution"},"category":{"type":"string","enum":["SYSTEM_FAILURE","AGENT_FAILURE","BILLING_FAILURE","UNKNOWN"],"description":"Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).","example":"SYSTEM_FAILURE"},"retry_after":{"type":"number","nullable":true,"description":"Suggested retry delay in seconds (null if not retryable)","example":60},"help_url":{"type":"string","description":"URL to documentation for troubleshooting","example":"https://docs.tinyfish.ai/prompting-guide"},"help_message":{"type":"string","description":"Human-readable help message with guidance","example":"Need help? Check out our goal prompting guide for tips and examples."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["message","category"],"description":"Error details. Null if the run succeeded."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["run_id","status","started_at","finished_at","num_of_steps","result","error"],"description":"Automation run response. Check status to determine success/failure. On success: result is populated, error is null. On failure: result is null, error contains message."},"examples":{"automationFailed":{"summary":"Automation execution failed","value":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"FAILED","started_at":"2024-01-01T00:00:00Z","finished_at":"2024-01-01T00:00:15Z","num_of_steps":3,"result":null,"error":{"message":"Browser crashed during execution"}}},"infrastructureError":{"summary":"Infrastructure error (before run creation)","value":{"run_id":null,"status":"FAILED","started_at":null,"finished_at":null,"num_of_steps":0,"result":null,"error":{"message":"Internal server error"}}}}}}}}}},"/v1/automation/run-async":{"post":{"operationId":"runAsync","summary":"Start automation asynchronously","description":"Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.","tags":["Automation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Automation task configuration","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Target website URL to automate","example":"https://example.com"},"goal":{"type":"string","minLength":1,"description":"Natural language description of what to accomplish on the website","example":"Find the pricing page and extract all plan details"},"browser_profile":{"type":"string","enum":["lite","stealth"],"description":"Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.","example":"lite"},"api_integration":{"type":"string","description":"Name of the integration making this API call (e.g., \"dify\", \"zapier\", \"n8n\"). Used for analytics.","example":"dify"},"agent_config":{"type":"object","properties":{"mode":{"type":"string","enum":["default","strict"],"description":"Agent behavior mode. \"strict\" enables fail-fast for test automation.","example":"strict"},"cursor_style":{"type":"string","enum":["fish","standard","green-pointer"],"description":"Cursor style for the browser agent.","example":"standard"},"max_steps":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum tool-call steps before the agent stops. Defaults to 150.","example":50},"max_duration_seconds":{"type":"integer","minimum":1,"description":"Maximum wall-clock seconds before the agent stops. Defaults to no limit.","example":300}},"description":"Agent behavior configuration","additionalProperties":false},"capture_config":{"type":"object","properties":{"elements":{"type":"boolean"},"snapshots":{"type":"boolean"},"screenshots":{"type":"boolean"},"recording":{"type":"boolean"},"html":{"type":"boolean"}},"description":"Configure which data to capture during the run.","additionalProperties":false},"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS."},"use_vault":{"type":"boolean","description":"Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.","example":true},"use_profile":{"type":"boolean","description":"Opt-in to the default Browser Context Profile if Browser Context Profiles are enabled; legacy callers are silently ignored when the profiles feature is disabled. Returns 400 when enabled but no default profile is set.","example":true},"profile_id":{"type":"string","minLength":1,"description":"Browser Context Profile ID to use when use_profile is true.","example":"prof_abc123def4567890"},"credential_item_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.","example":["cred:conn-abc:Work:item-123","cred:conn-def:Personal:item-456"]},"proxy_config":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable proxy for this automation run","example":true},"country_code":{"type":"string","enum":["US","GB","CA","DE","FR","JP","AU"],"description":"Country code for proxy location.","example":"US"}},"required":["enabled"],"description":"Proxy configuration","additionalProperties":false},"output_schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true},"description":"Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}}},"required":["url","goal"]}}}},"responses":{"200":{"description":"Run created and enqueued successfully. Returns run_id immediately. The automation will execute asynchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","nullable":true,"description":"Unique identifier for the created automation run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Error message if run creation failed","example":"Internal server error"}},"required":["code","message"],"description":"Error details. Null if successful."}},"required":["run_id","error"],"description":"Async automation run response. Returns run_id immediately without waiting for completion."},"example":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","error":null}}}},"400":{"description":"Invalid request - missing required fields or invalid format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required - wallet balance too low to start this run","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"403":{"description":"Forbidden - 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"}}}},"500":{"description":"Internal server error - Failed to create or enqueue the automation run","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"}}}}}}},"/v1/automation/run-batch":{"post":{"operationId":"runBatch","summary":"Start multiple automations asynchronously","description":"Creates and enqueues multiple automation runs in a single request, returning run_ids immediately without waiting for completion. Maximum 100 runs per request.\n\n**Atomic creation:** Run creation is all-or-nothing. Either all runs are created successfully, or none are (returns error).\n\n**Idempotency:** This endpoint does not currently support idempotency keys. Retrying a failed request may create duplicate runs.","tags":["Automation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Batch of automation task configurations","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Target website URL to automate","example":"https://example.com"},"goal":{"type":"string","minLength":1,"description":"Natural language description of what to accomplish on the website","example":"Find the pricing page and extract all plan details"},"browser_profile":{"type":"string","enum":["lite","stealth"],"description":"Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.","example":"lite"},"api_integration":{"type":"string","description":"Name of the integration making this API call (e.g., \"dify\", \"zapier\", \"n8n\"). Used for analytics.","example":"dify"},"agent_config":{"type":"object","properties":{"mode":{"type":"string","enum":["default","strict"],"description":"Agent behavior mode. \"strict\" enables fail-fast for test automation.","example":"strict"},"cursor_style":{"type":"string","enum":["fish","standard","green-pointer"],"description":"Cursor style for the browser agent.","example":"standard"},"max_steps":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum tool-call steps before the agent stops. Defaults to 150.","example":50},"max_duration_seconds":{"type":"integer","minimum":1,"description":"Maximum wall-clock seconds before the agent stops. Defaults to no limit.","example":300}},"description":"Agent behavior configuration","additionalProperties":false},"capture_config":{"type":"object","properties":{"elements":{"type":"boolean"},"snapshots":{"type":"boolean"},"screenshots":{"type":"boolean"},"recording":{"type":"boolean"},"html":{"type":"boolean"}},"description":"Configure which data to capture during the run.","additionalProperties":false},"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS."},"use_vault":{"type":"boolean","description":"Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.","example":true},"use_profile":{"type":"boolean","description":"Opt-in to the default Browser Context Profile if Browser Context Profiles are enabled; legacy callers are silently ignored when the profiles feature is disabled. Returns 400 when enabled but no default profile is set.","example":true},"credential_item_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.","example":["cred:conn-abc:Work:item-123","cred:conn-def:Personal:item-456"]},"proxy_config":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable proxy for this automation run","example":true},"country_code":{"type":"string","enum":["US","GB","CA","DE","FR","JP","AU"],"description":"Country code for proxy location.","example":"US"}},"required":["enabled"],"description":"Proxy configuration","additionalProperties":false}},"required":["url","goal"],"additionalProperties":false},"minItems":1,"maxItems":100,"description":"Array of run configurations (1-100)"},"profile_id":{"type":"string","minLength":1,"description":"Browser Context Profile ID to use when use_profile is true.","example":"prof_abc123def4567890"},"output_schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true},"description":"Optional provider-supported structured-output schema subset applied to every run in the batch. Unsupported fields are rejected before the request is accepted.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}}},"required":["runs"]}}}},"responses":{"200":{"description":"All runs created and enqueued successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"run_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Created run IDs. Null if creation failed.","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f23456789012"]},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Error code","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Error message","example":"Internal server error"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"],"description":"Error details. Null if successful."}},"required":["run_ids","error"],"description":"Batch async run response. Run creation is atomic. Returns run_ids on success, error on failure."},"example":{"run_ids":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f23456789012"],"error":null}}}},"400":{"description":"Invalid request - missing required fields, invalid format, or exceeds 100 runs","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required - wallet balance too low for the requested number of runs","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"403":{"description":"Forbidden - Insufficient credits for the requested number of runs","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 - Failed to create or enqueue any runs","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"}}}}}}},"/v1/runs":{"get":{"operationId":"listRuns","description":"List automation runs with optional filtering by status, goal text, and date range. Returns paginated results with total count. Default sort order is newest first.","summary":"List and search runs","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Filter by run status","example":"COMPLETED"},"required":false,"description":"Filter by run status","name":"status","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Filter runs by goal text (case-insensitive partial match)","example":"linkedin"},"required":false,"description":"Filter runs by goal text (case-insensitive partial match)","name":"goal","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter runs created after this ISO 8601 timestamp","example":"2026-01-01T00:00:00Z"},"required":false,"description":"Filter runs created after this ISO 8601 timestamp","name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter runs created before this ISO 8601 timestamp","example":"2026-02-01T00:00:00Z"},"required":false,"description":"Filter runs created before this ISO 8601 timestamp","name":"created_before","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order by created_at","example":"desc"},"required":false,"description":"Sort order by created_at","name":"sort_direction","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (from previous response)","example":"eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0="},"required":false,"description":"Cursor for pagination (from previous response)","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of results to return (1-100)","example":20},"required":false,"description":"Maximum number of results to return (1-100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","description":"Unique identifier for the run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Current status of the run","example":"COMPLETED"},"goal":{"type":"string","description":"Natural language goal for this automation run","example":"Find all pricing information"},"created_at":{"type":"string","description":"ISO 8601 timestamp when run was created","example":"2026-01-14T10:30:00Z"},"started_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run started executing","example":"2026-01-14T10:30:05Z"},"finished_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run finished","example":"2026-01-14T10:31:30Z"},"num_of_steps":{"type":"integer","nullable":true,"minimum":0,"description":"Number of steps taken during the automation run. Null while the run is still in progress.","example":5},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Extracted data from the automation run"},"output_schema":{"type":"object","nullable":true,"properties":{},"additionalProperties":{"nullable":true},"description":"Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}},"profile_attached":{"type":"boolean","description":"Whether this run attached a Browser Context Profile internally.","example":true},"profile_id":{"type":"string","nullable":true,"description":"Browser Context Profile ID attached to this run, or null when no profile attached.","example":"prof_abc123"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code for programmatic handling","example":"service_busy"},"message":{"type":"string","description":"Error message describing why the run failed","example":"Browser crashed during execution"},"category":{"type":"string","enum":["SYSTEM_FAILURE","AGENT_FAILURE","BILLING_FAILURE","UNKNOWN"],"description":"Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).","example":"SYSTEM_FAILURE"},"retry_after":{"type":"number","nullable":true,"description":"Suggested retry delay in seconds (null if not retryable)","example":60},"help_url":{"type":"string","description":"URL to documentation for troubleshooting","example":"https://docs.tinyfish.ai/prompting-guide"},"help_message":{"type":"string","description":"Human-readable help message with guidance","example":"Need help? Check out our goal prompting guide for tips and examples."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["message","category"],"description":"Error details. Null if the run succeeded or is still running."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."},"streaming_url":{"type":"string","nullable":true,"description":"URL to watch live browser session (available while running)","example":"https://stream.agent.tinyfish.ai/session/xyz"},"browser_config":{"type":"object","nullable":true,"properties":{"proxy_enabled":{"type":"boolean","nullable":true,"description":"Whether proxy was enabled","example":false},"proxy_country_code":{"type":"string","nullable":true,"description":"Country code for proxy","example":"US"}},"required":["proxy_enabled","proxy_country_code"],"description":"Browser configuration used for the run"}},"required":["run_id","status","goal","created_at","started_at","finished_at","num_of_steps","result","output_schema","profile_attached","profile_id","error","streaming_url","browser_config"],"description":"A run summary (without video_url and steps)"},"description":"Array of runs"},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of runs matching the current filters","example":142},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for fetching next page. Null if no more results.","example":"eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0="},"has_more":{"type":"boolean","description":"Whether there are more results after this page","example":true}},"required":["total","next_cursor","has_more"],"description":"Pagination information"}},"required":["data","pagination"],"description":"Paginated list of runs"}}}},"400":{"description":"Invalid request 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/batch":{"post":{"operationId":"batchGetRuns","summary":"Get multiple runs by IDs","description":"Retrieve multiple runs by their IDs in a single request. Returns found runs and lists any IDs that were not found or not owned. Maximum 100 IDs per request.","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Array of run IDs to fetch","content":{"application/json":{"schema":{"type":"object","properties":{"run_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Array of run IDs (1-100)","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f23456789012"]}},"required":["run_ids"],"description":"Batch runs request"}}}},"responses":{"200":{"description":"Request succeeded. Returns found runs in `data` and any missing IDs in `not_found`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","description":"Unique identifier for the run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Current status of the run","example":"COMPLETED"},"goal":{"type":"string","description":"Natural language goal for this automation run","example":"Find all pricing information"},"created_at":{"type":"string","description":"ISO 8601 timestamp when run was created","example":"2026-01-14T10:30:00Z"},"started_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run started executing","example":"2026-01-14T10:30:05Z"},"finished_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run finished","example":"2026-01-14T10:31:30Z"},"num_of_steps":{"type":"integer","nullable":true,"minimum":0,"description":"Number of steps taken during the automation run. Null while the run is still in progress.","example":5},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Extracted data from the automation run"},"output_schema":{"type":"object","nullable":true,"properties":{},"additionalProperties":{"nullable":true},"description":"Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}},"profile_attached":{"type":"boolean","description":"Whether this run attached a Browser Context Profile internally.","example":true},"profile_id":{"type":"string","nullable":true,"description":"Browser Context Profile ID attached to this run, or null when no profile attached.","example":"prof_abc123"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code for programmatic handling","example":"service_busy"},"message":{"type":"string","description":"Error message describing why the run failed","example":"Browser crashed during execution"},"category":{"type":"string","enum":["SYSTEM_FAILURE","AGENT_FAILURE","BILLING_FAILURE","UNKNOWN"],"description":"Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).","example":"SYSTEM_FAILURE"},"retry_after":{"type":"number","nullable":true,"description":"Suggested retry delay in seconds (null if not retryable)","example":60},"help_url":{"type":"string","description":"URL to documentation for troubleshooting","example":"https://docs.tinyfish.ai/prompting-guide"},"help_message":{"type":"string","description":"Human-readable help message with guidance","example":"Need help? Check out our goal prompting guide for tips and examples."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["message","category"],"description":"Error details. Null if the run succeeded or is still running."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."},"streaming_url":{"type":"string","nullable":true,"description":"URL to watch live browser session (available while running)","example":"https://stream.agent.tinyfish.ai/session/xyz"},"browser_config":{"type":"object","nullable":true,"properties":{"proxy_enabled":{"type":"boolean","nullable":true,"description":"Whether proxy was enabled","example":false},"proxy_country_code":{"type":"string","nullable":true,"description":"Country code for proxy","example":"US"}},"required":["proxy_enabled","proxy_country_code"],"description":"Browser configuration used for the run"},"video_url":{"type":"string","nullable":true,"description":"Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes.","example":"https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?..."},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this step","example":"evt_abc123"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when this step occurred","example":"2026-01-14T10:30:05Z"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Current status of the run","example":"COMPLETED"},"action":{"type":"string","nullable":true,"description":"Description of the action taken in this step","example":"Click the login button"},"screenshot":{"type":"string","nullable":true,"description":"Screenshot for this step. Format depends on the screenshots query param: base64 returns a data URI (data:image/jpeg;base64,...), url returns an absolute URL to the screenshot. Null if screenshots=none or no screenshot available.","example":"https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/screenshot"},"html":{"type":"string","nullable":true,"description":"URL to the full-page HTML snapshot captured at this step. Null if html=none or no HTML was captured. Requires capture_config.html: true when starting the run.","example":"https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/html"},"duration":{"type":"string","nullable":true,"description":"Time taken for this step","example":"1.2s"}},"required":["id","timestamp","status","action","screenshot","html","duration"],"description":"A single automation step"},"description":"Steps the agent took during this run."}},"required":["run_id","status","goal","created_at","started_at","finished_at","num_of_steps","result","output_schema","profile_attached","profile_id","error","streaming_url","browser_config","video_url","steps"],"description":"A single automation run"},"description":"Found runs"},"not_found":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Run IDs that were not found or not owned. Null if all found."}},"required":["data","not_found"],"description":"Batch get runs response"},"example":{"data":[{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"COMPLETED","goal":"Find all pricing information","created_at":"2024-01-01T00:00:00Z","started_at":"2024-01-01T00:00:05Z","finished_at":"2024-01-01T00:00:30Z","result":{"product":"iPhone 15","price":"$799"},"error":null}],"not_found":["b2c3d4e5-f6a7-8901-bcde-f23456789012"]}}}},"400":{"description":"Invalid request - empty array, exceeds 100 IDs, or malformed input","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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/batch/cancel":{"post":{"operationId":"batchCancelRuns","summary":"Cancel multiple runs by IDs","description":"Cancel multiple runs by their IDs in a single request. Returns per-run results including cancelled runs, already-terminal runs, and not-found IDs. Maximum 100 IDs per request. Idempotent: calling twice returns consistent results.","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"description":"Array of run IDs to cancel","content":{"application/json":{"schema":{"type":"object","properties":{"run_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Array of run IDs (1-100)","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f23456789012"]}},"required":["run_ids"],"description":"Batch runs request"}}}},"responses":{"200":{"description":"Request succeeded. Returns per-run results in `results` and any missing IDs in `not_found`.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","description":"The unique identifier of the run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["CANCELLED","COMPLETED","FAILED"],"description":"The current status of the run. Returns actual status for idempotent responses (e.g., COMPLETED if run already finished)","example":"CANCELLED"},"cancelled_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run was cancelled, or null if not cancelled","example":"2026-01-14T10:30:55Z"},"message":{"type":"string","nullable":true,"description":"Additional context about the cancellation result (e.g., \"Run already cancelled\", \"Run already finished\")","example":"Run already cancelled"}},"required":["run_id","status","cancelled_at","message"],"description":"Response from cancel run endpoint"},"description":"Results for runs that were found and processed (cancelled or already terminal)"},"not_found":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Run IDs that were not found or not owned. Null if all found."}},"required":["results","not_found"],"description":"Batch cancel runs response"},"example":{"results":[{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"CANCELLED","cancelled_at":"2024-01-01T00:00:30Z","message":null},{"run_id":"c3d4e5f6-a7b8-9012-cdef-345678901234","status":"COMPLETED","cancelled_at":null,"message":"Run already finished"}],"not_found":["b2c3d4e5-f6a7-8901-bcde-f23456789012"]}}}},"400":{"description":"Invalid request - empty array, exceeds 100 IDs, or malformed input","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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/{id}":{"get":{"operationId":"getRunById","description":"Get detailed information about a specific automation run by its ID.","summary":"Get run by ID","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Run ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":true,"description":"Run ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["base64","url","none"],"default":"url","description":"Screenshot delivery mode. url: absolute URLs to screenshot images. base64: inline data URIs. none: omit screenshots. Defaults to url.","example":"url"},"required":false,"description":"Screenshot delivery mode. url: absolute URLs to screenshot images. base64: inline data URIs. none: omit screenshots. Defaults to url.","name":"screenshots","in":"query"},{"schema":{"type":"string","enum":["url","none"],"default":"url","description":"HTML snapshot delivery mode. url: absolute URLs to HTML snapshot pages (only non-null when capture_config.html was enabled). none: omit HTML URLs. Defaults to url.","example":"url"},"required":false,"description":"HTML snapshot delivery mode. url: absolute URLs to HTML snapshot pages (only non-null when capture_config.html was enabled). none: omit HTML URLs. Defaults to url.","name":"html","in":"query"}],"responses":{"200":{"description":"Run details","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","description":"Unique identifier for the run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Current status of the run","example":"COMPLETED"},"goal":{"type":"string","description":"Natural language goal for this automation run","example":"Find all pricing information"},"created_at":{"type":"string","description":"ISO 8601 timestamp when run was created","example":"2026-01-14T10:30:00Z"},"started_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run started executing","example":"2026-01-14T10:30:05Z"},"finished_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when run finished","example":"2026-01-14T10:31:30Z"},"num_of_steps":{"type":"integer","nullable":true,"minimum":0,"description":"Number of steps taken during the automation run. Null while the run is still in progress.","example":5},"result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Extracted data from the automation run"},"output_schema":{"type":"object","nullable":true,"properties":{},"additionalProperties":{"nullable":true},"description":"Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided.","example":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"}},"required":["title","price"]}},"profile_attached":{"type":"boolean","description":"Whether this run attached a Browser Context Profile internally.","example":true},"profile_id":{"type":"string","nullable":true,"description":"Browser Context Profile ID attached to this run, or null when no profile attached.","example":"prof_abc123"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code for programmatic handling","example":"service_busy"},"message":{"type":"string","description":"Error message describing why the run failed","example":"Browser crashed during execution"},"category":{"type":"string","enum":["SYSTEM_FAILURE","AGENT_FAILURE","BILLING_FAILURE","UNKNOWN"],"description":"Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).","example":"SYSTEM_FAILURE"},"retry_after":{"type":"number","nullable":true,"description":"Suggested retry delay in seconds (null if not retryable)","example":60},"help_url":{"type":"string","description":"URL to documentation for troubleshooting","example":"https://docs.tinyfish.ai/prompting-guide"},"help_message":{"type":"string","description":"Human-readable help message with guidance","example":"Need help? Check out our goal prompting guide for tips and examples."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."}},"required":["message","category"],"description":"Error details. Null if the run succeeded or is still running."},"profile_hint":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable profile setup nudge for auth walls and bot challenges."},"setup_url":{"type":"string","description":"Internal URL to set up the caller’s default Browser Context Profile.","example":"/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge"},"reason":{"type":"string","enum":["auth_wall","bot_challenge"],"description":"Why a Browser Context Profile may solve this failed run.","example":"auth_wall"}},"required":["message","setup_url","reason"],"description":"Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile."},"streaming_url":{"type":"string","nullable":true,"description":"URL to watch live browser session (available while running)","example":"https://stream.agent.tinyfish.ai/session/xyz"},"browser_config":{"type":"object","nullable":true,"properties":{"proxy_enabled":{"type":"boolean","nullable":true,"description":"Whether proxy was enabled","example":false},"proxy_country_code":{"type":"string","nullable":true,"description":"Country code for proxy","example":"US"}},"required":["proxy_enabled","proxy_country_code"],"description":"Browser configuration used for the run"},"video_url":{"type":"string","nullable":true,"description":"Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes.","example":"https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?..."},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this step","example":"evt_abc123"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when this step occurred","example":"2026-01-14T10:30:05Z"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"Current status of the run","example":"COMPLETED"},"action":{"type":"string","nullable":true,"description":"Description of the action taken in this step","example":"Click the login button"},"screenshot":{"type":"string","nullable":true,"description":"Screenshot for this step. Format depends on the screenshots query param: base64 returns a data URI (data:image/jpeg;base64,...), url returns an absolute URL to the screenshot. Null if screenshots=none or no screenshot available.","example":"https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/screenshot"},"html":{"type":"string","nullable":true,"description":"URL to the full-page HTML snapshot captured at this step. Null if html=none or no HTML was captured. Requires capture_config.html: true when starting the run.","example":"https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/html"},"duration":{"type":"string","nullable":true,"description":"Time taken for this step","example":"1.2s"}},"required":["id","timestamp","status","action","screenshot","html","duration"],"description":"A single automation step"},"description":"Steps the agent took during this run."}},"required":["run_id","status","goal","created_at","started_at","finished_at","num_of_steps","result","output_schema","profile_attached","profile_id","error","streaming_url","browser_config","video_url","steps"],"description":"A single automation run"}}}},"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":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/{id}/cancel":{"post":{"operationId":"cancelRunById","description":"Cancel a run by ID. Only runs created via `/v1/automation/run-async` or `/v1/automation/run-sse` can be cancelled. Runs created via the synchronous `/v1/automation/run` endpoint cannot be cancelled.","summary":"Cancel run by ID","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Run ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":true,"description":"Run ID","name":"id","in":"path"}],"responses":{"200":{"description":"Run cancelled successfully, or already in terminal state (idempotent)","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","description":"The unique identifier of the run","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","enum":["CANCELLED","COMPLETED","FAILED"],"description":"The current status of the run. Returns actual status for idempotent responses (e.g., COMPLETED if run already finished)","example":"CANCELLED"},"cancelled_at":{"type":"string","nullable":true,"description":"ISO 8601 timestamp when the run was cancelled, or null if not cancelled","example":"2026-01-14T10:30:55Z"},"message":{"type":"string","nullable":true,"description":"Additional context about the cancellation result (e.g., \"Run already cancelled\", \"Run already finished\")","example":"Run already cancelled"}},"required":["run_id","status","cancelled_at","message"],"description":"Response from cancel run endpoint"},"examples":{"cancelled":{"summary":"Run cancelled","value":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"CANCELLED","cancelled_at":"2024-01-01T00:00:00Z","message":null}},"alreadycancelled":{"summary":"Run already cancelled (idempotent)","value":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"CANCELLED","cancelled_at":"2024-01-01T00:00:00Z","message":"Run already cancelled"}},"alreadyCompleted":{"summary":"Run already completed (no-op)","value":{"run_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"COMPLETED","cancelled_at":null,"message":"Run already finished"}}}}}},"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":"Run not found or not owned by this 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/{id}/steps/{stepId}/screenshot":{"get":{"operationId":"getStepScreenshot","description":"Serve the JPEG screenshot captured at a specific step via API key. Returns binary image data. Note: screenshots=url on GET /v1/runs/{id} returns browser-accessible URLs at /runs/{id}/steps/{stepId}/screenshot (session auth).","summary":"Get step screenshot","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Run ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":true,"description":"Run ID","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Step ID (event ID)","example":"evt_abc123"},"required":true,"description":"Step ID (event ID)","name":"stepId","in":"path"}],"responses":{"200":{"description":"JPEG screenshot image","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"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":"Run, step, or screenshot not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/runs/{id}/steps/{stepId}/html":{"get":{"operationId":"getStepHtml","description":"Serve the full-page HTML snapshot captured at a specific step via API key. Returns raw HTML. Only available when the run was started with capture_config.html: true.","summary":"Get step HTML snapshot","tags":["Runs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Run ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":true,"description":"Run ID","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Step ID (event ID)","example":"evt_abc123"},"required":true,"description":"Step ID (event ID)","name":"stepId","in":"path"}],"responses":{"200":{"description":"HTML snapshot","content":{"text/html":{"schema":{"type":"string"}}}},"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":"Run, step, or HTML snapshot not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles":{"get":{"operationId":"listBrowserContextProfiles","summary":"List Browser Context Profiles","description":"List Browser Context Profiles","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List Browser Context Profiles succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"name":{"type":"string","description":"Browser Context Profile display name","example":"Work Gmail"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null],"example":"US"},"is_default":{"type":"boolean","example":true},"fingerprint_seed":{"type":"string","example":"fp_abc123def456"},"domain_count":{"type":"integer","minimum":0,"example":3},"created_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"updated_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"signed_in_sites":{"type":"array","items":{"type":"object","properties":{"site":{"type":"string","description":"Registered domain (eTLD+1)","example":"github.com"},"claimed_at":{"type":"string","example":"2026-06-10T12:00:00Z"}},"required":["site","claimed_at"]},"description":"Sites TinyFish saw the user sign in to during a setup, or that the user confirmed when saving it, whose cookies are still saved. Does not guarantee the session is still valid. Omitted when sign-in tracking is not enabled for the account."}},"required":["id","name","created_at"]}}},"required":["profiles"]}}}},"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 Context Profiles are not available or the resource was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}},"post":{"operationId":"createBrowserContextProfile","summary":"Create a Browser Context Profile","description":"Create a Browser Context Profile","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"set_as_default":{"type":"boolean"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null]}},"required":["name"],"description":"Create a Browser Context Profile."}}}},"responses":{"201":{"description":"Create a Browser Context Profile succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"name":{"type":"string","description":"Browser Context Profile display name","example":"Work Gmail"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null],"example":"US"},"is_default":{"type":"boolean","example":true},"fingerprint_seed":{"type":"string","example":"fp_abc123def456"},"domain_count":{"type":"integer","minimum":0,"example":3},"created_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"updated_at":{"type":"string","example":"2026-06-10T12:00:00Z"}},"required":["id","name","created_at"]}}}},"400":{"description":"Invalid request body.","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 Context Profiles are not available or the resource was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}":{"get":{"operationId":"getBrowserContextProfile","summary":"Get a Browser Context Profile","description":"Get a Browser Context Profile","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"responses":{"200":{"description":"Get a Browser Context Profile succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"name":{"type":"string","description":"Browser Context Profile display name","example":"Work Gmail"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null],"example":"US"},"is_default":{"type":"boolean","example":true},"fingerprint_seed":{"type":"string","example":"fp_abc123def456"},"domain_count":{"type":"integer","minimum":0,"example":3},"created_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"updated_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"example.com"},"cookie_count":{"type":"integer","minimum":0,"example":12},"local_storage_origin_count":{"type":"integer","minimum":0,"example":1},"last_accessed_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"last_written_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"last_written_by_run_id":{"type":"string","example":"run_abc123"}},"required":["domain","cookie_count","local_storage_origin_count","last_accessed_at","last_written_at","last_written_by_run_id"]}}},"required":["id","name","created_at","domains"]}}}},"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 Context Profile not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}},"patch":{"operationId":"updateBrowserContextProfile","summary":"Update a Browser Context Profile","description":"Update a Browser Context Profile","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"set_as_default":{"type":"boolean"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null]}},"description":"Update Browser Context Profile metadata."}}}},"responses":{"200":{"description":"Update a Browser Context Profile succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"name":{"type":"string","description":"Browser Context Profile display name","example":"Work Gmail"},"proxy_country_code":{"type":"string","nullable":true,"enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","JP","SG","BR","IN",null],"example":"US"},"is_default":{"type":"boolean","example":true},"fingerprint_seed":{"type":"string","example":"fp_abc123def456"},"domain_count":{"type":"integer","minimum":0,"example":3},"created_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"updated_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"example.com"},"cookie_count":{"type":"integer","minimum":0,"example":12},"local_storage_origin_count":{"type":"integer","minimum":0,"example":1},"last_accessed_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"last_written_at":{"type":"string","example":"2026-06-10T12:00:00Z"},"last_written_by_run_id":{"type":"string","example":"run_abc123"}},"required":["domain","cookie_count","local_storage_origin_count","last_accessed_at","last_written_at","last_written_by_run_id"]}}},"required":["id","name","created_at","domains"]}}}},"400":{"description":"Invalid request body.","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 Context Profile not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}},"delete":{"operationId":"deleteBrowserContextProfile","summary":"Delete a Browser Context Profile","description":"Delete a Browser Context Profile","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"responses":{"200":{"description":"Delete a Browser Context Profile succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}},"required":["deleted"]}}}},"400":{"description":"Cannot delete the only Browser Context Profile.","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 Context Profile not found.","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":"Delete cleanup is still in progress; 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}/setup-session":{"post":{"operationId":"createBrowserContextProfileSetupSession","summary":"Create a profile setup session","description":"Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session is cancelled or times out.","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"requestBody":{"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}},"description":"Browser session creation parameters"}}}},"responses":{"201":{"description":"Create a profile setup session succeeded.","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"},"timeout_seconds":{"type":"integer","example":300},"expires_at":{"type":"string","example":"2026-06-10T12:05:00Z"}},"required":["session_id","cdp_url","base_url","timeout_seconds","expires_at"]}}}},"400":{"description":"Invalid request body or profile state too large.","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 Context Profile not found.","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":"Setup session cleanup or binding conflict; 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}/setup-session/cancel":{"post":{"operationId":"cancelBrowserContextProfileSetupSession","summary":"Cancel a profile setup session","description":"Cancels a running Browser Context Profile setup session and discards unsaved setup state. Requires the session_id returned by setup-session.","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","minLength":1,"example":"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["session_id"]}}}},"responses":{"200":{"description":"Cancel a profile setup session succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"boolean","example":true}},"required":["cancelled"]}}}},"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 session not found.","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":"Setup session cleanup failed; 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}/save":{"post":{"operationId":"saveBrowserContextProfileSetupSession","summary":"Save a profile setup session","description":"Captures cookies, local storage, and session storage from a running setup session into the Browser Context Profile. Requires the session_id returned by setup-session.","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","minLength":1,"example":"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"signed_in_sites":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":20,"description":"Sites the user says they signed into during this setup, as hosts or URLs. Each is recorded as signed in only if this save wrote cookies for it; for sites TinyFish can check, its sign-in cookie must be saved too. Ignored when sign-in tracking is not enabled for the account.","example":["facebook.com"]}},"required":["session_id"]}}}},"responses":{"200":{"description":"Save a profile setup session succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"domains_updated":{"type":"array","items":{"type":"string"},"example":["example.com"]},"domains_failed":{"type":"array","items":{"type":"string"},"example":[]},"cookie_count":{"type":"integer","minimum":0,"example":12},"domains_skipped":{"type":"object","properties":{"cookies_skipped":{"type":"array","items":{"type":"string"},"example":[]},"local_storage_skipped":{"type":"array","items":{"type":"string"},"example":[]},"session_storage_skipped":{"type":"array","items":{"type":"string"},"example":[]},"blob_too_large":{"type":"array","items":{"type":"string"},"example":[]}},"required":["cookies_skipped","local_storage_skipped","session_storage_skipped","blob_too_large"]},"pages_captured":{"type":"integer","minimum":0,"example":1},"target_reads_skipped":{"type":"integer","minimum":0,"example":0},"cleanup_failed":{"type":"boolean","example":false},"cleanup_kind":{"type":"string","example":"post_save"},"signed_in_sites":{"type":"array","items":{"type":"string"},"description":"Sites this save recorded as signed in, from sign-in cookies set during setup. Omitted when sign-in tracking is not enabled for the account.","example":["github.com"]},"sign_in":{"type":"object","properties":{"site":{"type":"string","nullable":true},"status":{"type":"string","enum":["recorded","already_recorded","not_detected","unverifiable"]}},"required":["site","status"],"description":"Whether TinyFish saw a sign-in to the site setup started on. unverifiable when it cannot tell. Omitted when sign-in tracking is not enabled for the account.","example":{"site":"github.com","status":"recorded"}},"user_confirmed_sites":{"type":"object","properties":{"recorded":{"type":"array","items":{"type":"string"}},"rejected":{"type":"array","items":{"type":"object","properties":{"site":{"type":"string"},"reason":{"type":"string","enum":["invalid_site","not_saved","no_sign_in_cookie","record_failed"]}},"required":["site","reason"]}}},"required":["recorded","rejected"],"description":"Present when the request sent signed_in_sites and sign-in tracking is enabled for the account: the registered domains recorded as signed in, and the sites rejected with a reason.","example":{"recorded":["facebook.com"],"rejected":[{"site":"notion.so","reason":"not_saved"}]}}},"required":["domains_updated","domains_failed","cookie_count","domains_skipped"]}}}},"400":{"description":"Captured state is invalid or exceeds limits.","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 Context Profile or setup session not found.","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":"Browser session is inactive, the profile is busy, or cleanup requires 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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}/upload":{"post":{"operationId":"uploadBrowserContextProfileState","summary":"Upload Browser Context Profile state","description":"Upload Browser Context Profile state","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cookies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":4096},"value":{"type":"string","maxLength":16384},"domain":{"type":"string","minLength":1,"maxLength":255},"path":{"type":"string","maxLength":4096},"httpOnly":{"type":"boolean"},"secure":{"type":"boolean"},"sameSite":{"type":"string","enum":["Strict","Lax","None"]},"expires":{"type":"number"},"sourceScheme":{"type":"string","maxLength":10},"sourcePort":{"type":"number"},"partitionKey":{"type":"string","nullable":true,"maxLength":255},"priority":{"type":"string","enum":["Low","Medium","High"]}},"required":["name","value","domain"],"additionalProperties":{"nullable":true}},"maxItems":3000},"localStorage":{"type":"array","items":{"type":"object","properties":{"origin":{"type":"string","minLength":1,"maxLength":2048},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":4096},"value":{"type":"string","maxLength":5242880}},"required":["name","value"]}}},"required":["origin","items"]},"maxItems":100},"sessionStorage":{"type":"array","items":{"type":"object","properties":{"origin":{"type":"string","minLength":1,"maxLength":2048},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":4096},"value":{"type":"string","maxLength":5242880}},"required":["name","value"]}}},"required":["origin","items"]},"maxItems":100}},"required":["cookies"]}}}},"responses":{"200":{"description":"Upload Browser Context Profile state succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"domains_updated":{"type":"array","items":{"type":"string"},"example":["example.com"]},"domains_failed":{"type":"array","items":{"type":"string"},"example":[]},"cookie_count":{"type":"integer","minimum":0,"example":12},"domains_skipped":{"type":"object","properties":{"cookies_skipped":{"type":"array","items":{"type":"string"},"example":[]},"local_storage_skipped":{"type":"array","items":{"type":"string"},"example":[]},"session_storage_skipped":{"type":"array","items":{"type":"string"},"example":[]},"blob_too_large":{"type":"array","items":{"type":"string"},"example":[]}},"required":["cookies_skipped","local_storage_skipped","session_storage_skipped","blob_too_large"]}},"required":["domains_updated","domains_failed","cookie_count","domains_skipped"]}}}},"400":{"description":"Upload body is invalid or exceeds limits.","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 Context Profile not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/profiles/{profileId}/domains/{domain}":{"delete":{"operationId":"deleteBrowserContextProfileDomain","summary":"Delete a saved profile domain","description":"Delete a saved profile domain","tags":["Browser Context Profiles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Browser Context Profile ID","example":"prof_abc123def4567890"},"required":true,"description":"Browser Context Profile ID","name":"profileId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Domain to remove from the Browser Context Profile","example":"example.com"},"required":true,"description":"Domain to remove from the Browser Context Profile","name":"domain","in":"path"}],"responses":{"200":{"description":"Delete a saved profile domain succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}},"required":["deleted"]}}}},"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 Context Profile or domain not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/vault/connections":{"post":{"operationId":"connectVault","summary":"Connect a vault provider","description":"Connect a supported password manager and immediately sync display-safe credential metadata.","tags":["Vault"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["1password","bitwarden"],"description":"Vault provider identifier.","example":"1password"},"token":{"type":"string","description":"1Password service account token. Required when provider is 1password."},"clientId":{"type":"string","description":"Bitwarden client ID. Required when provider is bitwarden."},"clientSecret":{"type":"string","description":"Bitwarden client secret. Required when provider is bitwarden."},"masterPassword":{"type":"string","description":"Bitwarden master password. Required when provider is bitwarden."},"serverUrl":{"type":"string","format":"uri","description":"Optional self-hosted Bitwarden server URL.","example":"https://vault.example.com"}},"required":["provider"],"description":"Connect a vault provider. For `1password`, provide `token`. For `bitwarden`, provide `clientId`, `clientSecret`, and `masterPassword`."}}}},"responses":{"200":{"description":"Vault connected successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","example":"conn_123"},"connected":{"type":"boolean","enum":[true]},"provider":{"type":"string","enum":["1password","bitwarden"],"description":"Vault provider identifier.","example":"1password"},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"cred:conn-123:Personal:item-abc123"},"connectionId":{"type":"string","nullable":true,"example":"conn_123"},"label":{"type":"string","example":"Amazon Login"},"vaultName":{"type":"string","example":"Personal"},"domains":{"type":"array","items":{"type":"string"},"example":["amazon.com"]},"fieldMetadata":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string","example":"password"},"label":{"type":"string","example":"Password"},"type":{"type":"string","enum":["STRING","CONCEALED","OTP"],"example":"CONCEALED"}},"required":["fieldId","label","type"],"description":"Metadata for a single vault field."}},"hasTotp":{"type":"boolean","example":true}},"required":["itemId","connectionId","label","vaultName","domains","fieldMetadata","hasTotp"],"description":"Display-safe vault item metadata."}}},"required":["connectionId","connected","provider","items"]}}}},"400":{"description":"Invalid request body or provider credentials.","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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Vault feature is not enabled","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"}}}}}},"get":{"operationId":"listVaultConnections","summary":"List vault connections","description":"List all connected vault providers for the authenticated user.","tags":["Vault"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Vault connections retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"conn_123"},"provider":{"type":"string","enum":["1password","bitwarden"],"description":"Vault provider identifier.","example":"1password"},"connectionStatus":{"type":"string","example":"connected"},"lastValidatedAt":{"type":"string","nullable":true,"example":"2026-04-05T12:00:00Z"}},"required":["id","provider","connectionStatus","lastValidatedAt"]}}},"required":["connections"]}}}},"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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Vault feature is not enabled","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"}}}}}}},"/v1/vault/connections/{connectionId}":{"delete":{"operationId":"disconnectVault","summary":"Disconnect a vault provider","description":"Disconnect a vault provider and remove its stored enabled items.","tags":["Vault"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"conn_123"},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Vault disconnected successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"disconnected":{"type":"boolean","enum":[true]},"connectionId":{"type":"string","example":"conn_123"}},"required":["disconnected","connectionId"]}}}},"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":"Vault connection not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Vault feature is not enabled","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"}}}}}}},"/v1/vault/items":{"get":{"operationId":"listVaultItems","summary":"List vault items","description":"List all vault items currently available from connected providers.","tags":["Vault"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Vault items retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"cred:conn-123:Personal:item-abc123"},"connectionId":{"type":"string","nullable":true,"example":"conn_123"},"label":{"type":"string","example":"Amazon Login"},"vaultName":{"type":"string","example":"Personal"},"domains":{"type":"array","items":{"type":"string"},"example":["amazon.com"]},"fieldMetadata":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string","example":"password"},"label":{"type":"string","example":"Password"},"type":{"type":"string","enum":["STRING","CONCEALED","OTP"],"example":"CONCEALED"}},"required":["fieldId","label","type"],"description":"Metadata for a single vault field."}},"hasTotp":{"type":"boolean","example":true}},"required":["itemId","connectionId","label","vaultName","domains","fieldMetadata","hasTotp"],"description":"Display-safe vault item metadata."}}},"required":["items"]}}}},"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":"No vault connection found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Vault feature is not enabled","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"}}}}}}},"/v1/vault/items/sync":{"post":{"operationId":"syncVaultItems","summary":"Sync vault items","description":"Sync items from connected providers and return merged item state plus sync counters.","tags":["Vault"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Vault items synced successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"cred:conn-123:Personal:item-abc123"},"connectionId":{"type":"string","nullable":true,"example":"conn_123"},"label":{"type":"string","example":"Amazon Login"},"vaultName":{"type":"string","example":"Personal"},"domains":{"type":"array","items":{"type":"string"},"example":["amazon.com"]},"fieldMetadata":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string","example":"password"},"label":{"type":"string","example":"Password"},"type":{"type":"string","enum":["STRING","CONCEALED","OTP"],"example":"CONCEALED"}},"required":["fieldId","label","type"],"description":"Metadata for a single vault field."}},"hasTotp":{"type":"boolean","example":true}},"required":["itemId","connectionId","label","vaultName","domains","fieldMetadata","hasTotp"],"description":"Display-safe vault item metadata."}},"sync_summary":{"type":"object","properties":{"added":{"type":"integer","minimum":0,"example":3},"updated":{"type":"integer","minimum":0,"example":1},"removed":{"type":"integer","minimum":0,"example":0}},"required":["added","updated","removed"]}},"required":["items","sync_summary"]}}}},"401":{"description":"Unauthorized - Invalid or missing API key, or vault connection expired and requires reconnection.","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":"No vault connection found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"503":{"description":"Vault feature is not enabled or vault service unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/wallet":{"get":{"operationId":"getWallet","description":"Get the caller's wallet: current balance, auto-reload configuration, per-product contract rates, and any in-flight top-up.","summary":"Get wallet","tags":["Wallet"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Wallet details","content":{"application/json":{"schema":{"type":"object","properties":{"available_balance":{"type":"string","pattern":"^-?(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Current spendable balance, denominated in `currency`. A negative value means the wallet is overdrawn.","example":"21.44"},"currency":{"type":"string","enum":["USD"],"example":"USD"},"as_of":{"type":"string","format":"date-time","example":"2026-08-10T18:04:11.220Z"},"auto_reload":{"oneOf":[{"type":"object","properties":{"state":{"type":"string","enum":["unconfigured"]}},"required":["state"],"description":"Auto-reload has never been configured for this wallet."},{"type":"object","properties":{"state":{"type":"string","enum":["on"]},"threshold":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance floor that triggers a reload, denominated in the response's `currency`.","example":"5.00"},"recharge_to":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.","example":"25.00"}},"required":["state","threshold","recharge_to"],"description":"Auto-reload is configured, current state \"on\"."},{"type":"object","properties":{"state":{"type":"string","enum":["off"]},"threshold":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance floor that triggers a reload, denominated in the response's `currency`.","example":"5.00"},"recharge_to":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.","example":"25.00"}},"required":["state","threshold","recharge_to"],"description":"Auto-reload is configured, current state \"off\"."},{"type":"object","properties":{"state":{"type":"string","enum":["paused_payment_failed"]},"threshold":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance floor that triggers a reload, denominated in the response's `currency`.","example":"5.00"},"recharge_to":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.","example":"25.00"}},"required":["state","threshold","recharge_to"],"description":"Auto-reload is configured, current state \"paused_payment_failed\"."},{"type":"object","properties":{"state":{"type":"string","enum":["needs_payment_method"]},"threshold":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance floor that triggers a reload, denominated in the response's `currency`.","example":"5.00"},"recharge_to":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.","example":"25.00"}},"required":["state","threshold","recharge_to"],"description":"Auto-reload is configured, current state \"needs_payment_method\"."},{"nullable":true}],"description":"null means the auto-reload contract read failed, not that it is unconfigured."},"pending_top_up":{"type":"object","nullable":true,"properties":{"amount":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Amount of the in-flight top-up, denominated in the response's `currency`.","example":"50.00"},"started_at":{"type":"string","format":"date-time","example":"2026-08-10T18:02:55.000Z"}},"required":["amount","started_at"],"description":"null means no in-flight top-up, or the ledger read failed."},"rates":{"type":"object","nullable":true,"properties":{"meters":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable meter label.","example":"Agent steps"},"unit_amount":{"type":"string","pattern":"^(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Per-unit rate, decimal USD string.","example":"0.016000"},"currency":{"type":"string","enum":["USD"],"example":"USD"},"per":{"type":"string","description":"Billable unit this meter charges per (e.g. \"step\"). Absent when unlabeled.","example":"step"}},"required":["label","unit_amount","currency"],"description":"One priced product on the caller's rate contract."}},"as_of":{"type":"string","format":"date-time","example":"2026-08-10T18:04:11.220Z"}},"required":["meters","as_of"],"description":"null means the rates read failed, or the wallet has no rate contract yet."},"agent_top_up_url":{"type":"string","format":"uri","description":"Present when an agent can add funds itself: POST here and pay the 402 MPP challenge.","example":"https://agent.tinyfish.ai/v1/wallet/top-up"}},"required":["available_balance","currency","as_of","auto_reload","pending_top_up","rates"],"description":"Wallet balance, auto-reload, per-product rates, and any in-flight top-up."}}}},"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":"The account is not assigned to wallet billing (error code FEATURE_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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}},"/v1/wallet/top-up":{"post":{"operationId":"topUpWallet","description":"Add money to the wallet, paid by the calling agent over the Machine Payments Protocol (MPP). The first call answers 402 with a payment challenge in WWW-Authenticate; retry with a Payment-Authorization credential to settle the charge and credit the wallet.","summary":"Top up wallet (agent-paid)","tags":["Wallet"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,2})?$","description":"Amount to add in USD, from 10.00 to 500.00. Charged over MPP once the agent presents a payment credential.","example":"25.00"}},"required":["amount"],"description":"A wallet top-up an agent pays for with the Machine Payments Protocol."}}}},"responses":{"200":{"description":"Payment settled and wallet credited","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"],"description":"settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again."},"amount":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","example":"25.00"},"currency":{"type":"string","enum":["USD"],"example":"USD"},"payment_reference":{"type":"string","description":"Stripe PaymentIntent that settled this top-up.","example":"pi_3QxYz2Ab"},"ledger_entry_id":{"type":"string","nullable":true,"example":"wallet-grant:machine-payment:pi_3QxYz2Ab"},"available_balance":{"type":"string","nullable":true,"pattern":"^-?(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Spendable balance after the credit landed; null when pending or unreadable.","example":"31.44"},"hint":{"type":"string","description":"On a 202: do not pay again."}},"required":["status","amount","currency","payment_reference","ledger_entry_id","available_balance"],"description":"The settled top-up and the balance it produced."}}}},"202":{"description":"Payment settled; the wallet credit is pending and lands via webhook. Do not pay again.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"],"description":"settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again."},"amount":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","example":"25.00"},"currency":{"type":"string","enum":["USD"],"example":"USD"},"payment_reference":{"type":"string","description":"Stripe PaymentIntent that settled this top-up.","example":"pi_3QxYz2Ab"},"ledger_entry_id":{"type":"string","nullable":true,"example":"wallet-grant:machine-payment:pi_3QxYz2Ab"},"available_balance":{"type":"string","nullable":true,"pattern":"^-?(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,6})?$","description":"Spendable balance after the credit landed; null when pending or unreadable.","example":"31.44"},"hint":{"type":"string","description":"On a 202: do not pay again."}},"required":["status","amount","currency","payment_reference","ledger_entry_id","available_balance"],"description":"The settled top-up and the balance it produced."}}}},"400":{"description":"Invalid amount (error code INVALID_INPUT)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}},"402":{"description":"Payment required. Either an MPP challenge in the WWW-Authenticate header (pay it and retry), or, after a payment that was not accepted, a problem body with no challenge and a hint (do not pay again on your own).","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"MPP problem type, on a challenge."},"title":{"type":"string"},"status":{"type":"number","enum":[402]},"detail":{"type":"string"},"challengeId":{"type":"string"},"hint":{"type":"string","description":"On a paid retry that was not accepted: do not pay again on your own."}},"required":["status"],"description":"Without a payment: an MPP challenge to pay and retry. With one that was not accepted: no new challenge, and a hint."}}}},"404":{"description":"Agent-paid top-ups are not enabled on this deployment, or the account is not on wallet billing (error code FEATURE_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"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","INVALID_INPUT","RATE_LIMIT_EXCEEDED","DAILY_LIMIT_EXCEEDED","INTERNAL_ERROR","RETRY_REQUIRED","UNAUTHORIZED","VAULT_RECONNECT_REQUIRED","FORBIDDEN","NOT_FOUND","FEATURE_NOT_AVAILABLE","SERVICE_BUSY","TIMEOUT","INSUFFICIENT_CREDITS","CONTENT_POLICY_VIOLATION","MAX_STEPS_EXCEEDED","SITE_BLOCKED","TASK_FAILED","CANCELLED"],"description":"Machine-readable error code","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error message","example":"Field \"url\" is required and must be a string"},"details":{"nullable":true,"description":"Additional error details (validation errors, etc.)"}},"required":["code","message"]},"request_id":{"type":"string","description":"Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues.","example":"8f9dba20-e37b-4749-a919-2269e28b4a2c"}},"required":["error"],"description":"Standard error response format"}}}}}}}}}