Tasks

Tasks are agent-run units of work created from templates (agent goals) such as a connector health audit. The REST API lets you create a task from a template, check whether your account satisfies a template’s prerequisites, start a run, and cancel the latest run.

Tasks require the Automations feature to be enabled for your workspace. When it is not, these endpoints return a feature-gate error.

Create Task


POST /api/v1/tasks

Creates an agent task from a template. Requires the tasks.write permission.

Request Body

Field	Type	Required	Description
`template_id`	string	Yes	Agent goal id (e.g. `connector_health_audit`)
`title`	string	No	Title override; defaults to the template name
`params`	object	No	Launch-time parameters, validated against the template’s parameter schema

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "connector_health_audit" }' \
  https://app2.vendodata.com/api/v1/tasks

Example Response

Returns 201 Created:


{
  "data": {
    "task_id": "task_123"
  }
}

Precheck a Template


POST /api/v1/templates/{templateId}/precheck

Before creating a task, check whether your account satisfies a template’s prerequisites (for example, an active app of each required type). Requires the tasks.read permission. No request body is needed.

Example Response


{
  "data": {
    "ready": false,
    "gaps": [
      {
        "kind": "missing_integration",
        "capability": {
          "type": "app",
          "name": "Shopify",
          "appType": "shopify"
        },
        "hint": "Connect a Shopify app to run this template."
      }
    ]
  }
}

Gap kinds are missing_integration, missing_permission, and missing_data.

Start Task Run


POST /api/v1/tasks/{taskId}/start

Starts a run for the task. Requires the tasks.manage permission. An optional JSON body can supply run parameters:

Field	Type	Required	Description
`params`	object	No	Run-time parameters for this run

Example Response

Returns 202 Accepted:


{
  "data": {
    "task_run_id": "run_123",
    "params": {}
  }
}

A 409 Conflict is returned when a run is already pending or running for the task.

Cancel Task Run


POST /api/v1/tasks/{taskId}/cancel

Cancels the latest pending or running run for the task. Requires the tasks.manage permission.

Example Response


{
  "data": {
    "cancelled": true,
    "task_run_id": "run_123"
  }
}

cancelled is false (with task_run_id: null) when there is no active run to cancel.

Listing Tasks

The REST v1 surface does not currently expose a task list endpoint. Use the Vendo app, or the MCP server tools (tasks_list, tasks_get), to browse existing tasks.