Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
task v2 api doc (#1573)
Shuchang Zheng0d0c4f562699
diff --git a/docs/mint.json b/docs/mint.jsonindex eb2eb1270..fd7bfb3ca 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -69,6 +69,7 @@"pages": ["running-tasks/introduction","running-tasks/api-spec",+ "running-tasks/api-v2-spec","running-tasks/webhooks-faq","running-tasks/visualizing-results","running-tasks/advanced-features"diff --git a/docs/running-tasks/api-v2-spec.mdx b/docs/running-tasks/api-v2-spec.mdxnew file mode 100644index 000000000..086791c6b--- /dev/null+++ b/docs/running-tasks/api-v2-spec.mdx@@ -0,0 +1,98 @@+---+title: Tasks API V2+description: 'The latest version of Skyvern agent task, with better reasoning and validation'+---++## Request - Initiate a task+Request type: `POST`++Production:`https://api.skyvern.com/api/v2/tasks/`++### Header++| Parameter | Type | Required? | Sample Value | Description |+| --- | --- | --- | --- | --- |+| x-api-key | String | yes | [your-api-key-here] | Bearer token that gives your backend access to the Skyvern API. This will be manually provided by us |+| x-max-iterations-override | Integer | no | 10 | The max number of iterations skyvern attempts to divide and conquer a complicated task. In each iteration, Skyvern does a "mini task" planning, mini task execution and validation. The default is 10. |++### Body++| Parameter | Type | Required? | Sample Value | Description |+| --- | --- | --- | --- | --- |+| user_prompt | String | yes | Apply for a job | The prompt that tells the agent what the user-facing goal is. This is the guiding light for the LLM as it navigates a particular website / sitemap to achieve this specified goal |+| url | HttpUrl | no | https://www.example.com | If you want to use a specific url, you can pass it here. It's optional since you can also tell skyvern which site to go to in the user_prompt. |+| webhook_callback_url | HttpUrl | no | … | The callback URL once our system is finished processing this async task |+| proxy_location | String | no | RESIDENTIAL | Proxy location for the web-browsing request. Please pass RESIDENTIAL as a value |+| totp_verification_url | HttpUrl | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint. If this field is provided, Skyvern will call the url to fetch the TOTP/2FA/MFA code when needed |+| totp_identifier | String | no | [email protected] / 4155558888 | The email address or the phone number which receives the TOTP/2FA/MFA code. If this field is provided, Skyvern will fetch the code that is pushed to [Skyvern's TOTP API](https://docs.skyvern.com/running-tasks/advanced-features#push-code-to-skyvern) |++## Example Request (Apply for a job)++```python+POST https://api.skyvern.com/api/v2/tasks/++{+ "user_prompt": "Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: [email protected]",+ "proxy_location": "RESIDENTIAL"+}+```++## Response+Each task has an associated `task_id` -- a unique identifier you can use to look up information about any task.++| Parameter | Type | Always returned? | Sample Value | Description |+| --- | --- | --- | --- | --- |+| task_id | String | yes | t_123456 | The task id associated with this specific task |+| status | String | yes | created | The status of the task |+| prompt | String | yes | Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: [email protected] | The user_prompt that skyvern received. |+| url | HttpUrl | yes | https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply | The url that skyvern starts browsing with |+| organization_id | String | yes | o_123456 | The organization id associated with this task |+| workflow_id | String | yes | wf_123456 | The workflow id created by this task |+| workflow_run_id | String | yes | wr_123456 | The ID of the workflow run |+| workflow_permanent_id | String | yes | wpid_123456 | The workflow permanent id |+| summary | String | no | The summary of what skyvern did when the task is completed |+| output | Object | no | { "name": "Chris P. Bacon", "email": "[email protected]" } | The output of the task. This is the structured data that skyvern extracted from the website. |+| webhook_callback_url | HttpUrl | no | https://mywebsite.com/webhook | The url of your webhook endpoint if sent to execute the task. |+| totp_verification_url | HttpUrl | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint if sent to execute the task. |+| totp_identifier | String | no | [email protected] / 4155558888 | The totp_identifier sent to execute the task.|+| proxy_location | String | no | RESIDENTIAL | The proxy location used to execute the task. |+| created_at | Timestamp | yes | 2022-11-22T22:55:55 | The timestamp when the task was created. |+| modified_at | Timestamp | yes | 2022-11-22T22:55:55 | The timestamp when the task was last updated. |+++## Response Webhook - Task conclusion (POST)+If a `webhook_callback_url` is specified within your task request, Skyvern will make a callback to your system letting you know that it has either finished, terminated or failed a task execution.++The following headers can be used to validate it's an authentic Skyvern request.++### Headers++| Parameter | Type | Required? | Sample Value | Description |+| --- | --- | --- | --- | --- |+| x-skyvern-signature | String | yes | v0=a2114d57b48eac39b9ad189<br/>dd8316235a7b4a8d21a10bd275<br/>19666489c69b503 | Authentication token that allows our service to communicate with your backend service via callback / webhook <br/>We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |+| x-skyvern-timestamp | String | yes | 1531420618 | Timestamp used to decode and validate the incoming webhook call<br/><br/>We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |++### Body+These parameters are sent in the body of the request to `webhook_callback_url`.++Here's an example of the webhook body:+```+{+ "task_id": "oc_347318612592634222",+ "status": "completed",+ "organization_id": "o_123456",+ "workflow_run_id": "wr_123456",+ "workflow_id": "w_123456",+ "workflow_permanent_id": "wpid_123456",+ "prompt": "Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: [email protected]",+ "url": "https://www.coursera.org/",+ "summary": "The user successfully applied for a job.",+ "output": null,+ "totp_verification_url": null,+ "totp_identifier": null,+ "proxy_location": null,+ "webhook_callback_url": null,+ "created_at": "2025-01-10T22:53:36.297774Z",+ "modified_at": "2025-01-10T22:56:29.582779Z"+}+```\ No newline at end of filediff --git a/docs/workflows/creating-workflows.mdx b/docs/workflows/creating-workflows.mdxindex b2a8aadd0..cf4e47539 100644--- a/docs/workflows/creating-workflows.mdx+++ b/docs/workflows/creating-workflows.mdx@@ -241,3 +241,10 @@ workflow_definition:- SKYVERN_DOWNLOAD_DIRECTORY```++## Update Workflows (YAML)+`PUT api.skyvern.com/api/v1/workflows/{workflow_permanent_id}`++Workflows are versioned. Each time you create a new workflow or update the workflow, you will get a new workflow_id and but the workflow_permanent_id will remain the same.++The update workflow API payload should be exactly the same as the create workflow API payload, a YAML.\ No newline at end of filediff --git a/skyvern/forge/sdk/services/observer_service.py b/skyvern/forge/sdk/services/observer_service.pyindex ca1f8adf7..eb911d230 100644--- a/skyvern/forge/sdk/services/observer_service.py+++ b/skyvern/forge/sdk/services/observer_service.py@@ -1236,7 +1236,7 @@ async def send_observer_cruise_webhook(observer_cruise: ObserverTask) -> None:)return# build the observer cruise response- payload = observer_cruise.model_dump_json()+ payload = observer_cruise.model_dump_json(by_alias=True)headers = generate_skyvern_webhook_headers(payload=payload, api_key=api_key.token)LOG.info("Sending observer cruise response to webhook callback url",