From d2419d82d74cc13cf3d74e755bc4b6fcdfaa27a1 Mon Sep 17 00:00:00 2001 From: Shuchang Zheng Date: Fri, 16 May 2025 19:06:41 -0700 Subject: [PATCH] update documentation part3 - add code examples (#2369) --- fern/openapi/skyvern_openapi.json | 1231 ++++++++++++++------ skyvern/forge/sdk/routes/agent_protocol.py | 22 + skyvern/forge/sdk/routes/code_samples.py | 18 + skyvern/forge/sdk/schemas/credentials.py | 4 +- 4 files changed, 922 insertions(+), 353 deletions(-) create mode 100644 skyvern/forge/sdk/routes/code_samples.py diff --git a/fern/openapi/skyvern_openapi.json b/fern/openapi/skyvern_openapi.json index e2de0625..3ac63922 100644 --- a/fern/openapi/skyvern_openapi.json +++ b/fern/openapi/skyvern_openapi.json @@ -22,6 +22,11 @@ "schema": { "type": "string", "description": "The id of the task run or the workflow run.", + "examples": [ + "tsk_123", + "tsk_v2_123", + "wr_123" + ], "title": "Run Id" }, "description": "The id of the task run or the workflow run." @@ -182,8 +187,13 @@ "required": true, "schema": { "type": "string", + "description": "The ID of the workflow to update. Workflow ID starts with `wpid_`.", + "examples": [ + "wpid_123" + ], "title": "Workflow Id" - } + }, + "description": "The ID of the workflow to update. Workflow ID starts with `wpid_`." }, { "name": "x-api-key", @@ -1507,6 +1517,11 @@ "default": true, "title": "Complete Verification", "type": "boolean" + }, + "include_action_history_in_verification": { + "default": false, + "title": "Include Action History In Verification", + "type": "boolean" } }, "required": [ @@ -1888,6 +1903,11 @@ "default": true, "title": "Complete Verification", "type": "boolean" + }, + "include_action_history_in_verification": { + "default": false, + "title": "Include Action History In Verification", + "type": "boolean" } }, "required": [ @@ -2533,8 +2553,13 @@ "required": true, "schema": { "type": "string", + "description": "The ID of the workflow to delete. Workflow ID starts with `wpid_`.", + "examples": [ + "wpid_123" + ], "title": "Workflow Id" - } + }, + "description": "The ID of the workflow to delete. Workflow ID starts with `wpid_`." }, { "name": "x-api-key", @@ -2894,10 +2919,405 @@ "x-fern-sdk-method-name": "cancel_run" } }, + "/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" + }, + "403": { + "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" + } + } + } + }, + "403": { + "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" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateBrowserSessionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully created browser session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BrowserSessionResponse" + } + } + } + }, + "403": { + "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": { + + } + } + } + }, + "403": { + "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" + } + }, + "/v1/credentials/totp": { + "post": { + "tags": [ + "Credentials" + ], + "summary": "Forward TOTP (2FA, MFA) code to Skyvern", + "description": "Forward a TOTP (2FA, MFA) code to Skyvern", + "operationId": "send_totp_code_v1_credentials_totp_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/TOTPCodeCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TOTPCode" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + }, + "x-fern-sdk-group-name": "credentials", + "x-fern-sdk-method-name": "send_totp_code" + } + }, "/v1/credentials": { "get": { "tags": [ - "credentials" + "Credentials" ], "summary": "Get all credentials", "description": "Retrieves a paginated list of credentials for the current organization", @@ -3001,7 +3421,7 @@ }, "post": { "tags": [ - "credentials" + "Credentials" ], "summary": "Create credential", "description": "Creates a new credential for the current organization", @@ -3092,7 +3512,7 @@ "/v1/credentials/{credential_id}": { "get": { "tags": [ - "credentials" + "Credentials" ], "summary": "Get credential by ID", "description": "Retrieves a specific credential by its ID", @@ -3175,7 +3595,7 @@ "/v1/credentials/{credential_id}/delete": { "post": { "tags": [ - "credentials" + "Credentials" ], "summary": "Delete credential", "description": "Deletes a specific credential by its ID", @@ -3247,313 +3667,6 @@ "x-fern-sdk-group-name": "credentials", "x-fern-sdk-method-name": "delete_credential" } - }, - "/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": { @@ -3857,6 +3970,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -4200,11 +4318,49 @@ "title": "Runnable Id", "description": "ID of the associated runnable" }, + "timeout": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Timeout", + "description": "Timeout in minutes for the session. Timeout is applied after the session is started." + }, + "started_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Started At", + "description": "Timestamp when the session was started" + }, + "completed_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Completed At", + "description": "Timestamp when the session was completed" + }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", - "description": "Timestamp when the session was created" + "description": "Timestamp when the session was created (the timestamp for the initial request)" }, "modified_at": { "type": "string", @@ -4405,6 +4561,27 @@ ], "title": "ContextParameter" }, + "CreateBrowserSessionRequest": { + "properties": { + "timeout": { + "anyOf": [ + { + "type": "integer", + "maximum": 10080, + "minimum": 5 + }, + { + "type": "null" + } + ], + "title": "Timeout", + "description": "Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 10080. Defaults to 60.", + "default": 60 + } + }, + "type": "object", + "title": "CreateBrowserSessionRequest" + }, "CreateCredentialRequest": { "properties": { "name": { @@ -4853,6 +5030,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -5093,6 +5275,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -5705,6 +5892,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -5937,6 +6129,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -6310,6 +6507,250 @@ ], "title": "SendEmailBlock" }, + "TOTPCode": { + "properties": { + "totp_identifier": { + "type": "string", + "title": "Totp Identifier", + "description": "The identifier of the TOTP code. It can be the email address, phone number, or the identifier of the user.", + "examples": [ + "john.doe@example.com", + "4155555555", + "user_123" + ] + }, + "task_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Task Id", + "description": "The task_id the totp code is for. It can be the task_id of the task that the TOTP code is for.", + "examples": [ + "task_123456" + ] + }, + "workflow_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Workflow Id", + "description": "The workflow ID the TOTP code is for. It can be the workflow ID of the workflow that the TOTP code is for.", + "examples": [ + "wpid_123456" + ] + }, + "workflow_run_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Workflow Run Id", + "description": "The workflow run id that the TOTP code is for. It can be the workflow run id of the workflow run that the TOTP code is for.", + "examples": [ + "wr_123456" + ] + }, + "source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source", + "description": "An optional field. The source of the TOTP code. e.g. email, sms, etc.", + "examples": [ + "email", + "sms", + "app" + ] + }, + "content": { + "type": "string", + "title": "Content", + "description": "The content of the TOTP code. It can be the email content that contains the TOTP code, or the sms message that contains the TOTP code. Skyvern will automatically extract the TOTP code from the content.", + "examples": [ + "Hello, your verification code is 123456" + ] + }, + "expired_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Expired At", + "description": "The timestamp when the TOTP code expires", + "examples": [ + "2025-01-01T00:00:00Z" + ] + }, + "totp_code_id": { + "type": "string", + "title": "Totp Code Id", + "description": "The skyvern ID of the TOTP code." + }, + "code": { + "type": "string", + "title": "Code", + "description": "The TOTP code extracted from the content." + }, + "organization_id": { + "type": "string", + "title": "Organization Id", + "description": "The ID of the organization that the TOTP code is for." + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "Created At", + "description": "The timestamp when the TOTP code was created." + }, + "modified_at": { + "type": "string", + "format": "date-time", + "title": "Modified At", + "description": "The timestamp when the TOTP code was modified." + } + }, + "type": "object", + "required": [ + "totp_identifier", + "content", + "totp_code_id", + "code", + "organization_id", + "created_at", + "modified_at" + ], + "title": "TOTPCode" + }, + "TOTPCodeCreate": { + "properties": { + "totp_identifier": { + "type": "string", + "title": "Totp Identifier", + "description": "The identifier of the TOTP code. It can be the email address, phone number, or the identifier of the user.", + "examples": [ + "john.doe@example.com", + "4155555555", + "user_123" + ] + }, + "task_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Task Id", + "description": "The task_id the totp code is for. It can be the task_id of the task that the TOTP code is for.", + "examples": [ + "task_123456" + ] + }, + "workflow_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Workflow Id", + "description": "The workflow ID the TOTP code is for. It can be the workflow ID of the workflow that the TOTP code is for.", + "examples": [ + "wpid_123456" + ] + }, + "workflow_run_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Workflow Run Id", + "description": "The workflow run id that the TOTP code is for. It can be the workflow run id of the workflow run that the TOTP code is for.", + "examples": [ + "wr_123456" + ] + }, + "source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source", + "description": "An optional field. The source of the TOTP code. e.g. email, sms, etc.", + "examples": [ + "email", + "sms", + "app" + ] + }, + "content": { + "type": "string", + "title": "Content", + "description": "The content of the TOTP code. It can be the email content that contains the TOTP code, or the sms message that contains the TOTP code. Skyvern will automatically extract the TOTP code from the content.", + "examples": [ + "Hello, your verification code is 123456" + ] + }, + "expired_at": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Expired At", + "description": "The timestamp when the TOTP code expires", + "examples": [ + "2025-01-01T00:00:00Z" + ] + } + }, + "type": "object", + "required": [ + "totp_identifier", + "content" + ], + "title": "TOTPCodeCreate" + }, "TaskBlock": { "properties": { "label": { @@ -6540,6 +6981,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -6568,6 +7014,11 @@ "title": "Url", "description": "The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL" }, + "engine": { + "$ref": "#/components/schemas/RunEngine", + "description": "The Skyvern engine version to use for this task. The default value is skyvern-2.0.", + "default": "skyvern-2.0" + }, "title": { "anyOf": [ { @@ -6578,12 +7029,7 @@ } ], "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" + "description": "The title for the task" }, "proxy_location": { "anyOf": [ @@ -6697,7 +7143,20 @@ "publish_workflow": { "type": "boolean", "title": "Publish Workflow", - "description": "Whether to publish this task as a reusable workflow. ", + "description": "Whether to publish this task as a reusable workflow. Only available for skyvern-2.0.", + "default": false + }, + "include_action_history_in_verification": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Include Action History In Verification", + "description": "Whether to include action history when verifying that the task is complete", "default": false } }, @@ -6712,11 +7171,26 @@ "run_id": { "type": "string", "title": "Run Id", - "description": "Unique identifier for this run" + "description": "Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs.", + "examples": [ + "tsk_123", + "tsk_v2_123", + "wr_123" + ] }, "status": { "$ref": "#/components/schemas/RunStatus", - "description": "Current status of the run" + "description": "Current status of the run", + "examples": [ + "created", + "queued", + "running", + "timed_out", + "failed", + "terminated", + "completed", + "canceled" + ] }, "output": { "anyOf": [ @@ -6738,7 +7212,7 @@ } ], "title": "Output", - "description": "Output data from the run, if any. Format depends on the schema in the input" + "description": "Output data from the run, if any. Format/schema depends on the data extracted by the run." }, "downloaded_files": { "anyOf": [ @@ -6777,19 +7251,25 @@ } ], "title": "Failure Reason", - "description": "Reason for failure if the run failed" + "description": "Reason for failure if the run failed or terminated" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", - "description": "Timestamp when this run was created" + "description": "Timestamp when this run was created", + "examples": [ + "2025-01-01T00:00:00Z" + ] }, "modified_at": { "type": "string", "format": "date-time", "title": "Modified At", - "description": "Timestamp when this run was last modified" + "description": "Timestamp when this run was last modified", + "examples": [ + "2025-01-01T00:05:00Z" + ] }, "app_url": { "anyOf": [ @@ -6801,7 +7281,11 @@ } ], "title": "App Url", - "description": "URL to the application UI where the run can be viewed" + "description": "URL to the application UI where the run can be viewed", + "examples": [ + "https://app.skyvern.com/tasks/tsk_123", + "https://app.skyvern.com/workflows/wpid_123/wr_123" + ] }, "run_type": { "type": "string", @@ -7270,6 +7754,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -7510,6 +7999,11 @@ "type": "boolean", "title": "Complete Verification", "default": true + }, + "include_action_history_in_verification": { + "type": "boolean", + "title": "Include Action History In Verification", + "default": false } }, "type": "object", @@ -8020,7 +8514,19 @@ "workflow_id": { "type": "string", "title": "Workflow Id", - "description": "ID of the workflow to run" + "description": "ID of the workflow to run. Workflow ID starts with `wpid_`.", + "examples": [ + "wpid_123" + ] + }, + "parameters": { + "additionalProperties": true, + "type": "object", + "title": "Parameters", + "description": "Parameters to pass to the workflow", + "default": { + + } }, "title": { "anyOf": [ @@ -8032,19 +8538,17 @@ } ], "title": "Title", - "description": "Optional title for this workflow run" - }, - "parameters": { - "additionalProperties": true, - "type": "object", - "title": "Parameters", - "description": "Parameters to pass to the workflow", - "default": { - - } + "description": "The title for this workflow run" }, "proxy_location": { - "$ref": "#/components/schemas/ProxyLocation", + "anyOf": [ + { + "$ref": "#/components/schemas/ProxyLocation" + }, + { + "type": "null" + } + ], "description": "Location of proxy to use for this workflow run", "default": "RESIDENTIAL" }, @@ -8058,7 +8562,7 @@ } ], "title": "Webhook Url", - "description": "URL to send workflow status updates to after a run is finished" + "description": "URL to send workflow status updates to after a run is finished. Refer to https://docs.skyvern.com/running-tasks/webhooks-faq for webhook questions." }, "totp_url": { "anyOf": [ @@ -8070,7 +8574,7 @@ } ], "title": "Totp Url", - "description": "URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes" + "description": "URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://docs.skyvern.com/running-tasks/advanced-features#get-code-from-your-endpoint" }, "totp_identifier": { "anyOf": [ @@ -8082,7 +8586,7 @@ } ], "title": "Totp Identifier", - "description": "Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern" + "description": "Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://docs.skyvern.com/running-tasks/advanced-features#time-based-one-time-password-totp" }, "browser_session_id": { "anyOf": [ @@ -8094,7 +8598,7 @@ } ], "title": "Browser Session Id", - "description": "ID of an existing browser session to reuse, having it continue from the current screen state" + "description": "ID of a Skyvern browser session to reuse, having it continue from the current screen state" } }, "type": "object", @@ -8108,11 +8612,26 @@ "run_id": { "type": "string", "title": "Run Id", - "description": "Unique identifier for this run" + "description": "Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs.", + "examples": [ + "tsk_123", + "tsk_v2_123", + "wr_123" + ] }, "status": { "$ref": "#/components/schemas/RunStatus", - "description": "Current status of the run" + "description": "Current status of the run", + "examples": [ + "created", + "queued", + "running", + "timed_out", + "failed", + "terminated", + "completed", + "canceled" + ] }, "output": { "anyOf": [ @@ -8134,7 +8653,7 @@ } ], "title": "Output", - "description": "Output data from the run, if any. Format depends on the schema in the input" + "description": "Output data from the run, if any. Format/schema depends on the data extracted by the run." }, "downloaded_files": { "anyOf": [ @@ -8173,19 +8692,25 @@ } ], "title": "Failure Reason", - "description": "Reason for failure if the run failed" + "description": "Reason for failure if the run failed or terminated" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", - "description": "Timestamp when this run was created" + "description": "Timestamp when this run was created", + "examples": [ + "2025-01-01T00:00:00Z" + ] }, "modified_at": { "type": "string", "format": "date-time", "title": "Modified At", - "description": "Timestamp when this run was last modified" + "description": "Timestamp when this run was last modified", + "examples": [ + "2025-01-01T00:05:00Z" + ] }, "app_url": { "anyOf": [ @@ -8197,7 +8722,11 @@ } ], "title": "App Url", - "description": "URL to the application UI where the run can be viewed" + "description": "URL to the application UI where the run can be viewed", + "examples": [ + "https://app.skyvern.com/tasks/tsk_123", + "https://app.skyvern.com/workflows/wpid_123/wr_123" + ] }, "run_type": { "type": "string", diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py index 1f0fa402..77903e6f 100644 --- a/skyvern/forge/sdk/routes/agent_protocol.py +++ b/skyvern/forge/sdk/routes/agent_protocol.py @@ -23,6 +23,7 @@ from skyvern.forge.sdk.core.security import generate_skyvern_signature from skyvern.forge.sdk.db.enums import OrganizationAuthTokenType from skyvern.forge.sdk.executor.factory import AsyncExecutorFactory from skyvern.forge.sdk.models import Step +from skyvern.forge.sdk.routes.code_samples import GET_RUN_CODE_SAMPLE, RUN_TASK_CODE_SAMPLE, RUN_WORKFLOW_CODE_SAMPLE from skyvern.forge.sdk.routes.routers import base_router, legacy_base_router, legacy_v2_router from skyvern.forge.sdk.schemas.ai_suggestions import AISuggestionBase, AISuggestionRequest from skyvern.forge.sdk.schemas.organizations import ( @@ -417,6 +418,7 @@ async def get_runs( openapi_extra={ "x-fern-sdk-group-name": "agent", "x-fern-sdk-method-name": "get_run", + "x-fern-examples": [{"code-samples": [{"sdk": "python", "code": GET_RUN_CODE_SAMPLE}]}], }, responses={ 200: {"description": "Successfully got run"}, @@ -1423,6 +1425,16 @@ async def _flatten_workflow_run_timeline(organization_id: str, workflow_run_id: openapi_extra={ "x-fern-sdk-group-name": "agent", "x-fern-sdk-method-name": "run_task", + "x-fern-examples": [ + { + "code-samples": [ + { + "sdk": "python", + "code": RUN_TASK_CODE_SAMPLE, + } + ] + } + ], }, description="Run a task", summary="Run a task", @@ -1582,6 +1594,16 @@ async def run_task( openapi_extra={ "x-fern-sdk-group-name": "agent", "x-fern-sdk-method-name": "run_workflow", + "x-fern-examples": [ + { + "code-samples": [ + { + "sdk": "python", + "code": RUN_WORKFLOW_CODE_SAMPLE, + } + ] + } + ], }, description="Run a workflow", summary="Run a workflow", diff --git a/skyvern/forge/sdk/routes/code_samples.py b/skyvern/forge/sdk/routes/code_samples.py new file mode 100644 index 00000000..a4e6c31b --- /dev/null +++ b/skyvern/forge/sdk/routes/code_samples.py @@ -0,0 +1,18 @@ +RUN_TASK_CODE_SAMPLE = """from skyvern import Skyvern + +client = Skyvern(api_key="your_api_key") +await client.run_task(prompt="What's the top post on hackernews?") +""" + +GET_RUN_CODE_SAMPLE = """from skyvern import Skyvern + +client = Skyvern(api_key="your_api_key") +run = await client.get_run(run_id="tsk_123") +print(run) +""" + +RUN_WORKFLOW_CODE_SAMPLE = """from skyvern import Skyvern + +client = Skyvern(api_key="your_api_key") +await client.agent.run_workflow(workflow_id="wpid_123", parameters={"parameter1": "value1", "parameter2": "value2"}) +""" diff --git a/skyvern/forge/sdk/schemas/credentials.py b/skyvern/forge/sdk/schemas/credentials.py index 188590ba..bc2af88a 100644 --- a/skyvern/forge/sdk/schemas/credentials.py +++ b/skyvern/forge/sdk/schemas/credentials.py @@ -92,7 +92,7 @@ class CredentialItem(BaseModel): class CreateCredentialRequest(BaseModel): """Request model for creating a new credential.""" - name: str = Field(..., description="Name of the credential", examples=["My Credential"]) + name: str = Field(..., description="Name of the credential", examples=["Amazon Login"]) credential_type: CredentialType = Field(..., description="Type of credential to create") credential: NonEmptyPasswordCredential | NonEmptyCreditCardCredential = Field( ..., @@ -109,7 +109,7 @@ class CredentialResponse(BaseModel): ..., description="The credential data" ) credential_type: CredentialType = Field(..., description="Type of the credential") - name: str = Field(..., description="Name of the credential", examples=["My Credential"]) + name: str = Field(..., description="Name of the credential", examples=["Amazon Login"]) class Credential(BaseModel):