{ "openapi": "3.1.0", "info": { "title": "Skyvern API", "description": "API for Skyvern", "version": "1.0.0" }, "paths": { "/v1/runs/{run_id}": { "get": { "tags": [ "agent" ], "summary": "Get Run", "operationId": "get_run_v1_runs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunResponse" }, { "$ref": "#/components/schemas/WorkflowRunResponse" } ], "discriminator": { "propertyName": "run_type", "mapping": { "task_v1": "#/components/schemas/TaskRunResponse", "task_v2": "#/components/schemas/TaskRunResponse", "workflow_run": "#/components/schemas/WorkflowRunResponse" } }, "title": "Response Get Run V1 Runs Run Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "agent", "x-fern-sdk-method-name": "get_run" } }, "/v1/tasks": { "post": { "tags": [ "Agent" ], "summary": "Run a task", "description": "Run a task", "operationId": "run_task_v1_tasks_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunRequest" } } } }, "responses": { "200": { "description": "Successfully run task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResponse" } } } }, "400": { "description": "Invalid agent engine" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "agent", "x-fern-sdk-method-name": "run_task" } }, "/v1/browser_sessions/{browser_session_id}": { "get": { "tags": [ "Browser Sessions" ], "summary": "Get browser session details", "description": "Get details about a specific browser session by ID", "operationId": "get_browser_session_v1_browser_sessions__browser_session_id__get", "parameters": [ { "name": "browser_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Browser Session Id" } }, { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successfully retrieved browser session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionResponse" } } } }, "404": { "description": "Browser session not found" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "browser_session", "x-fern-sdk-method-name": "get_browser_session" } }, "/v1/browser_sessions": { "get": { "tags": [ "Browser Sessions" ], "summary": "Get all active browser sessions", "description": "Get all active browser sessions for the organization", "operationId": "get_browser_sessions_v1_browser_sessions_get", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successfully retrieved all active browser sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserSessionResponse" }, "title": "Response Get Browser Sessions V1 Browser Sessions Get" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "browser_session", "x-fern-sdk-method-name": "get_browser_sessions" }, "post": { "tags": [ "Browser Sessions" ], "summary": "Create a new browser session", "description": "Create a new browser session", "operationId": "create_browser_session_v1_browser_sessions_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successfully created browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "browser_session", "x-fern-sdk-method-name": "create_browser_session" } }, "/v1/browser_sessions/{browser_session_id}/close": { "post": { "tags": [ "Browser Sessions" ], "summary": "Close a browser session", "description": "Close a browser session", "operationId": "close_browser_session_v1_browser_sessions__browser_session_id__close_post", "parameters": [ { "name": "browser_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Browser Session Id" } }, { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successfully closed browser session", "content": { "application/json": { "schema": { } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": "browser_session", "x-fern-sdk-method-name": "close_browser_session" } } }, "components": { "schemas": { "BrowserSessionResponse": { "properties": { "browser_session_id": { "type": "string", "title": "Browser Session Id", "description": "Unique identifier for the browser session" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "ID of the organization that owns this session" }, "runnable_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runnable Type", "description": "Type of runnable associated with this session (workflow, task etc)" }, "runnable_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runnable Id", "description": "ID of the associated runnable" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the session was created" }, "modified_at": { "type": "string", "format": "date-time", "title": "Modified At", "description": "Timestamp when the session was last modified" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Deleted At", "description": "Timestamp when the session was deleted, if applicable" } }, "type": "object", "required": [ "browser_session_id", "organization_id", "created_at", "modified_at" ], "title": "BrowserSessionResponse", "description": "Response model for browser session information." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ProxyLocation": { "type": "string", "enum": [ "RESIDENTIAL", "US-CA", "US-NY", "US-TX", "US-FL", "US-WA", "RESIDENTIAL_ES", "RESIDENTIAL_IE", "RESIDENTIAL_GB", "RESIDENTIAL_IN", "RESIDENTIAL_JP", "RESIDENTIAL_FR", "RESIDENTIAL_DE", "RESIDENTIAL_NZ", "RESIDENTIAL_ZA", "RESIDENTIAL_AR", "RESIDENTIAL_ISP", "NONE" ], "title": "ProxyLocation" }, "RunEngine": { "type": "string", "enum": [ "skyvern-1.0", "skyvern-2.0" ], "title": "RunEngine" }, "RunStatus": { "type": "string", "enum": [ "created", "queued", "running", "timed_out", "failed", "terminated", "completed", "canceled" ], "title": "RunStatus" }, "TaskRunRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "The goal or task description for Skyvern to accomplish" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Optional title for the task" }, "engine": { "$ref": "#/components/schemas/RunEngine", "description": "The Skyvern engine version to use for this task", "default": "skyvern-2.0" }, "proxy_location": { "anyOf": [ { "$ref": "#/components/schemas/ProxyLocation" }, { "type": "null" } ], "description": "Geographic Proxy location to route the browser traffic through", "default": "RESIDENTIAL" }, "data_extraction_schema": { "anyOf": [ { "type": "object" }, { "items": { }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Data Extraction Schema", "description": "Schema defining what data should be extracted from the webpage" }, "error_code_mapping": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Error Code Mapping", "description": "Custom mapping of error codes to error messages if Skyvern encounters an error" }, "max_steps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Steps", "description": "Maximum number of steps the task can take before timing out" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "URL to send task status updates to after a run is finished" }, "totp_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Identifier", "description": "Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern" }, "totp_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Url", "description": "URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes" }, "browser_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Browser Session Id", "description": "ID of an existing browser session to reuse, having it continue from the current screen state" }, "publish_workflow": { "type": "boolean", "title": "Publish Workflow", "description": "Whether to publish this task as a reusable workflow. ", "default": false } }, "type": "object", "required": [ "prompt" ], "title": "TaskRunRequest" }, "TaskRunResponse": { "properties": { "run_id": { "type": "string", "title": "Run Id", "description": "Unique identifier for this run" }, "status": { "$ref": "#/components/schemas/RunStatus", "description": "Current status of the run" }, "output": { "anyOf": [ { "type": "object" }, { "items": { }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Output", "description": "Output data from the run, if any. Format depends on the schema in the input" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "Reason for failure if the run failed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when this run was created" }, "modified_at": { "type": "string", "format": "date-time", "title": "Modified At", "description": "Timestamp when this run was last modified" }, "run_type": { "type": "string", "enum": [ "task_v1", "task_v2" ], "title": "Run Type", "description": "Type of task run - either task_v1 or task_v2" }, "run_request": { "anyOf": [ { "$ref": "#/components/schemas/TaskRunRequest" }, { "type": "null" } ], "description": "The original request parameters used to start this task run" } }, "type": "object", "required": [ "run_id", "status", "created_at", "modified_at", "run_type" ], "title": "TaskRunResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WorkflowRunRequest": { "properties": { "workflow_id": { "type": "string", "title": "Workflow Id", "description": "ID of the workflow to run" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Optional title for this workflow run" }, "parameters": { "type": "object", "title": "Parameters", "description": "Parameters to pass to the workflow", "default": { } }, "proxy_location": { "$ref": "#/components/schemas/ProxyLocation", "description": "Location of proxy to use for this workflow run", "default": "RESIDENTIAL" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "URL to send workflow status updates to after a run is finished" }, "totp_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Url", "description": "URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes" }, "totp_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Identifier", "description": "Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern" }, "browser_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Browser Session Id", "description": "ID of an existing browser session to reuse, having it continue from the current screen state" } }, "type": "object", "required": [ "workflow_id" ], "title": "WorkflowRunRequest" }, "WorkflowRunResponse": { "properties": { "run_id": { "type": "string", "title": "Run Id", "description": "Unique identifier for this run" }, "status": { "$ref": "#/components/schemas/RunStatus", "description": "Current status of the run" }, "output": { "anyOf": [ { "type": "object" }, { "items": { }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Output", "description": "Output data from the run, if any. Format depends on the schema in the input" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "Reason for failure if the run failed" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when this run was created" }, "modified_at": { "type": "string", "format": "date-time", "title": "Modified At", "description": "Timestamp when this run was last modified" }, "run_type": { "type": "string", "const": "workflow_run", "title": "Run Type", "description": "Type of run - always workflow_run for workflow runs" }, "run_request": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunRequest" }, { "type": "null" } ], "description": "The original request parameters used to start this workflow run" } }, "type": "object", "required": [ "run_id", "status", "created_at", "modified_at", "run_type" ], "title": "WorkflowRunResponse" } } }, "servers": [ { "url": "https://api.skyvern.com", "x-fern-server-name": "Production" }, { "url": "https://api-staging.skyvern.com", "x-fern-server-name": "Staging" }, { "url": "http://localhost:8000", "x-fern-server-name": "Development" } ] }