Vertesia Tasks API
Task endpoints manage durable human tasks used by process runs and agent asks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/vertesiahq:vertesiahq-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Vertesia Tasks API
version: 1.6.0-dev.20261019.172735Z
x-api-version: '20260803'
description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
contact:
name: Vertesia
url: https://vertesiahq.com/
license:
name: Apache-2.0
identifier: Apache-2.0
x-scalar-sdk-installation:
- lang: Node
description: 'Install the **Vertesia Client** from npm:'
source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
description: Vertesia API
variables:
region:
default: us1
enum:
- us1
- eu1
- jp1
description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Tasks
description: Task endpoints manage durable human tasks used by process runs and agent asks.
paths:
/tasks:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
get:
operationId: ListTasks
tags:
- Tasks
summary: List tasks
description: Lists durable tasks visible to the current principal, with optional filters for status, assignee, run id, and source type.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: status
in: query
required: false
schema:
type: array
items:
type: string
enum:
- pending
- in_progress
- completed
- cancelled
description: Durable human task types used by process human_task nodes and agent asks.
style: form
explode: true
- name: assignee
in: query
required: false
schema:
type: string
- name: run_id
in: query
required: false
schema:
type: string
- name: source_type
in: query
required: false
schema:
type: string
enum:
- process
- agent
- name: limit
in: query
required: false
schema:
type: number
minimum: 0
multipleOf: 1
- name: offset
in: query
required: false
schema:
type: number
minimum: 0
multipleOf: 1
responses:
'200':
description: Matching tasks.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskArray'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: list
post:
operationId: CreateTask
tags:
- Tasks
summary: Create a task
description: Creates a durable human task for a process or agent run. Callers must have `workflow:run` or `task:manage`.
security:
- bearerAuth: []
- OAuth2: []
parameters: []
responses:
'201':
description: The created task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskPayload'
/tasks/{taskId}:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
get:
operationId: GetTask
tags:
- Tasks
summary: Retrieve a task
description: Retrieves a single durable task by id.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: taskId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: get
put:
operationId: UpdateTask
tags:
- Tasks
summary: Update a task
description: 'Updates a durable task, including assignment, fields, due date, and status.
**Required permissions:** `task:manage`'
security:
- bearerAuth: []
- OAuth2:
- task:manage
parameters:
- name: taskId
in: path
required: true
schema:
type: string
responses:
'200':
description: The updated task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- task:manage
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: update
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTaskPayload'
delete:
operationId: DeleteTask
tags:
- Tasks
summary: Delete a task
description: 'Deletes a durable task by id.
**Required permissions:** `task:manage`'
security:
- bearerAuth: []
- OAuth2:
- task:manage
parameters:
- name: taskId
in: path
required: true
schema:
type: string
responses:
'200':
description: Task deletion result.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCountResult'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- task:manage
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: delete
/tasks/{taskId}/complete:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
post:
operationId: CompleteTask
tags:
- Tasks
summary: Complete a task
description: Completes a durable task and, for agent ask tasks, signals the backing workflow with the submitted result. Process `human_task` nodes should be resumed through `POST /agents/{agentRunId}/answer-task` instead of this endpoint.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: taskId
in: path
required: true
schema:
type: string
responses:
'200':
description: The completed task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: complete
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteTaskPayload'
/tasks/{taskId}/cancel:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
post:
operationId: CancelTask
tags:
- Tasks
summary: Cancel a task
description: 'Cancels a pending or in-progress durable task.
**Required permissions:** `task:manage`'
security:
- bearerAuth: []
- OAuth2:
- task:manage
parameters:
- name: taskId
in: path
required: true
schema:
type: string
responses:
'200':
description: The cancelled task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- task:manage
x-vertesia-source:
file: ../../apps/zeno-server/src/api/tasks.ts
className: TaskResource
methodName: cancel
components:
schemas:
DurableTaskStatus:
type: string
enum:
- pending
- in_progress
- completed
- cancelled
description: Durable human task types used by process human_task nodes and agent asks.
CreateTaskPayload:
type: object
properties:
title:
type: string
description:
type: string
assignee:
type: string
fields:
type: array
items:
$ref: '#/components/schemas/TaskField'
source:
$ref: '#/components/schemas/TaskSource'
due_at:
type: string
format: date-time
required:
- title
- source
additionalProperties: false
TaskFieldType:
type: string
enum:
- string
- number
- boolean
- select
- text
UpdateTaskPayload:
type: object
properties:
title:
type: string
description:
type: string
status:
$ref: '#/components/schemas/DurableTaskStatus'
assignee:
anyOf:
- type: string
- type: 'null'
fields:
type: array
items:
$ref: '#/components/schemas/TaskField'
due_at:
anyOf:
- type: string
format: date-time
- type: 'null'
additionalProperties: false
TaskSource:
type: object
properties:
type:
type: string
enum:
- process
- agent
run_id:
type: string
node:
type: string
ask_id:
type: string
required:
- type
- run_id
additionalProperties: false
DeleteCountResult:
type: object
properties:
id:
type: string
count:
type: number
required:
- id
- count
additionalProperties: false
CompleteTaskPayload:
type: object
properties:
result:
type: object
additionalProperties: true
required:
- result
additionalProperties: false
TaskArray:
type: array
items:
$ref: '#/components/schemas/Task'
Task:
type: object
properties:
id:
type: string
account:
type: string
project:
type: string
title:
type: string
description:
type: string
status:
$ref: '#/components/schemas/DurableTaskStatus'
assignee:
type: string
fields:
type: array
items:
$ref: '#/components/schemas/TaskField'
result:
type: object
additionalProperties: true
source:
$ref: '#/components/schemas/TaskSource'
due_at:
type: string
format: date-time
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- account
- project
- title
- status
- fields
- source
- created_at
additionalProperties: false
ErrorResponse:
type: object
description: Standard JSON error response returned by the server error handler.
properties:
error:
type: string
description: HTTP status text or normalized error type.
status:
type: integer
format: int32
minimum: 400
maximum: 599
description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
example: 400
message:
type: string
description: Human-readable error message.
details:
type: string
description: Optional additional error details.
errorCode:
type: string
description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
example: account_api_key_creation_disabled
required:
- error
- status
additionalProperties: false
TaskField:
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/TaskFieldType'
required:
type: boolean
label:
type: string
options:
type: array
items:
type: string
default: {}
required:
- name
- type
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
tokenUrl: https://sts.vertesia.io/oauth/token
x-scalar-security-query:
resource: https://api.us1.vertesia.io/api/v1
x-scalar-security-body:
resource: https://api.us1.vertesia.io/api/v1
scopes:
openid: ''
profile: ''
offline_access: ''
interaction:read: ''
interaction:write: ''
interaction:delete: ''
interaction:execute: ''
run:read: ''
run:write: ''
environment:admin: ''
app:manage: ''
project:admin: ''
project:integration_read: ''
project:settings_write: ''
api_key:read: ''
account:read: ''
account:write: ''
account:admin: ''
audit:read: ''
account:member: ''
content:read: ''
content:read_all: ''
content:write: ''
content:delete: ''
content:admin: ''
content:superadmin: ''
workflow:read: ''
workflow:run: ''
workflow:admin: ''
workflow:superadmin: ''
agent_run:read: ''
task:read: ''
task:manage: ''
x-tagGroups:
- name: Authentication
tags:
- Token Service
- name: GenAI
tags:
- Environments
- Prompt Templates
- Interactions
- Interaction Runs
- Agent Runs
- name: Content
tags:
- Content Object Types
- Objects
- Collections
- Files
- Rendering
- Bulk Operations
- Commands
- name: Data Store
tags:
- Data
- name: Workflow
tags:
- Processes
- Tasks
- Workflow Definitions
- Workflow Rules
- Workflow Runs
- name: Administration
tags:
- Accounts
- Projects
- Audit Trail
- Costs
- name: Access Control
tags:
- Users
- User Groups
- Roles
- Access Control Entries
- API Keys
- name: Apps & Integrations
tags:
- Apps
- OAuth Providers
- OAuth Clients
- OAuth Grants
- Remote MCP Connections