diff --git a/docs/mint.json b/docs/mint.json index eb2eb127..fd7bfb3c 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.mdx new file mode 100644 index 00000000..086791c6 --- /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 | myemail@example.com / 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: chris@pbacon.com", + "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: chris@pbacon.com | 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": "chris@pbacon.com" } | 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 | myemail@example.com / 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
dd8316235a7b4a8d21a10bd275
19666489c69b503 | Authentication token that allows our service to communicate with your backend service via callback / webhook
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

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: chris@pbacon.com", + "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 file diff --git a/docs/workflows/creating-workflows.mdx b/docs/workflows/creating-workflows.mdx index b2a8aadd..cf4e4753 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 file diff --git a/skyvern/forge/sdk/services/observer_service.py b/skyvern/forge/sdk/services/observer_service.py index ca1f8adf..eb911d23 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",