Vertesia

Vertesia Tasks API

Task endpoints manage durable human tasks used by process runs and agent asks.

GitHub OpenAPI

Operations 7

GET /tasks List tasks #
POST /tasks Create a task #
GET /tasks/{taskId} Retrieve a task #
PUT /tasks/{taskId} Update a task #
DELETE /tasks/{taskId} Delete a task #
POST /tasks/{taskId}/complete Complete a task #
POST /tasks/{taskId}/cancel Cancel a task #

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/openapi/vertesiahq-tasks-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-agent-run-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-update-app-payload-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-app-manifest-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-app-manifest-data-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-indexing-status-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-dashboard-schema.json

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.
All 92 tools →

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"

Discovery needs no key. Ratings and market analysis are Pro.

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

vertesiahq-tasks-api-openapi.yml Raw ↑ 
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