Vertesia Tools API

openapi: 3.2.0
info:
  title: Vertesia Tools 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: Tools
paths:
  /tools:
    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: ListAgentTools
      tags:
      - Tools
      summary: List all tools available in the project
      description: 'Returns the unified project-scoped tool registry visible to the current principal. Sources can be filtered via the `sources` query string.


        **Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters:
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - conversation
          - process
          description: The runtime context in which a caller intends to use a tool.
        style: form
      - name: sources
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - builtin
            - app
            - interaction
            description: 'Origin of a tool in the unified project-scoped tool registry.


              - `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills

              - `app`: tools contributed by an installed app for the project

              - `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`


              Skill semantics (the tool unlocks others when invoked) are NOT part of the source. They are identified universally by the `learn_` prefix in the tool name. This matches how the runtime registry stores them and avoids splitting one logical origin into two sources.'
          description: Include only these sources.
        description: Include only these sources.
        style: form
        explode: true
      - name: exclude
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - builtin
            - app
            - interaction
            description: 'Origin of a tool in the unified project-scoped tool registry.


              - `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills

              - `app`: tools contributed by an installed app for the project

              - `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`


              Skill semantics (the tool unlocks others when invoked) are NOT part of the source. They are identified universally by the `learn_` prefix in the tool name. This matches how the runtime registry stores them and avoids splitting one logical origin into two sources.'
          description: Drop these sources from the result (and skip their fetch). Applied after `sources`.
        description: Drop these sources from the result (and skip their fetch). Applied after `sources`.
        style: form
        explode: true
      responses:
        '200':
          description: Aggregated tool list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedToolArray'
        '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:
      - account:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/tools.ts
        className: ToolsResource
        methodName: list
  /tools/{toolName}:
    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: InspectProjectTool
      tags:
      - Tools
      summary: Inspect one project tool
      description: '**Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters:
      - name: toolName
        in: path
        required: true
        schema:
          type: string
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - conversation
          - process
          description: The runtime context in which a caller intends to use a tool.
        style: form
      responses:
        '200':
          description: Resolved tool details and input schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolInspection'
        '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:
      - account:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/tools.ts
        className: ToolsResource
        methodName: inspect
  /tools/validate:
    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: ValidateAgentToolNames
      tags:
      - Tools
      summary: Validate tool names against the project registry
      description: 'Resolves each name to its source or reports it as invalid with a suggestion.


        **Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters: []
      responses:
        '200':
          description: Per-name validation results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateToolNamesResponse'
        '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:
      - account:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/tools.ts
        className: ToolsResource
        methodName: validate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateToolNamesPayload'
components:
  schemas:
    AgentToolApprovalClass:
      type: string
      enum:
      - read_only
      - side_effecting
      - control
      - requires_confirmation
      description: 'Approval behavior class for a tool exposed to agents.


        - `read_only`: reads or inspects state without changing Vertesia, external systems, or user-visible artifacts.

        - `side_effecting`: can create, update, delete, send, execute, schedule, or otherwise change state.

        - `control`: affects agent control flow or tool availability, not user data or external systems.

        - `requires_confirmation`: high-impact action that must ask the user even in interactive full-control mode.'
    ProcessToolCompatibilityReason:
      type: string
      enum:
      - skill_not_supported
      - interaction_not_supported
      - agent_not_supported
      - confirmation_not_supported
      - control_tool_not_supported
      - approval_metadata_unavailable
      - ambiguous_name
    ProcessToolCompatibility:
      type: object
      properties:
        compatible:
          type: boolean
        reason:
          $ref: '#/components/schemas/ProcessToolCompatibilityReason'
      required:
      - compatible
      additionalProperties: false
    AggregatedTool:
      type: object
      properties:
        name:
          type: string
          description: Name as referenced from `agent_runner_options.tool_names`. For interaction skills this is `learn_<endpoint>`.
        source:
          $ref: '#/components/schemas/ToolSource'
        description:
          type: string
        title:
          type: string
        is_default:
          type: boolean
          description: Whether the tool is part of the default toolkit when no explicit `tool_names` is provided.
        annotations:
          $ref: '#/components/schemas/MCPToolAnnotations'
        approval_class:
          $ref: '#/components/schemas/AgentToolApprovalClass'
        process_compatibility:
          $ref: '#/components/schemas/ProcessToolCompatibility'
        unlocked_tools:
          type: array
          items:
            type: string
          description: 'For skills (`learn_*`): tool names this skill unlocks when invoked.'
        app_install_id:
          type: string
          description: 'Present when `source === ''app''`: the app installation that provides this tool.'
        app_name:
          type: string
          description: 'Present when `source === ''app''`: the app''s manifest name (used for `principal.apps` filtering).'
        interaction_id:
          type: string
          description: 'Present when `source === ''interaction''`: the interaction document id.'
        is_agent:
          type: boolean
          description: 'Present when `source === ''interaction''`: true if the interaction has `agent_runner_options.is_agent === true`. Lets UI consumers distinguish sub-agents (autonomous, run-to-completion) from regular interaction tools.'
      required:
      - name
      - source
      additionalProperties: false
      description: A single tool entry in the unified registry, regardless of where it came from. Returned by `GET /tools` and the resolution map of `POST /tools/validate`.
    ToolInspection:
      type: object
      properties:
        name:
          type: string
        source:
          $ref: '#/components/schemas/ToolSource'
        description:
          type: string
        title:
          type: string
        input_schema:
          $ref: '#/components/schemas/JSONSchema'
          description: Exact input schema when the provider supplied one. Omitted rather than fabricated.
        output_schema:
          $ref: '#/components/schemas/JSONSchema'
          description: MCP outputSchema advertised by the provider. It does not describe the process node result transport.
        output_contract_status:
          type: string
          enum:
          - provider_supplied
          - unknown
          description: For app tools, whether the provider advertised output schema metadata. Omitted for builtin and interaction tools.
        approval_class:
          $ref: '#/components/schemas/AgentToolApprovalClass'
        annotations:
          $ref: '#/components/schemas/MCPToolAnnotations'
        app_install_id:
          type: string
        app_name:
          type: string
        ready:
          type: boolean
          description: True only when an exact input schema was resolved.
        process_compatibility:
          $ref: '#/components/schemas/ProcessToolCompatibility'
      required:
      - name
      - source
      - ready
      additionalProperties: false
    JSONSchemaProperties:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JSONSchema'
    ToolValidationResult:
      type: object
      properties:
        name:
          type: string
          description: The name the caller asked about.
        valid:
          type: boolean
          description: True if the name resolves to exactly one tool in the project's unified registry.
        source:
          $ref: '#/components/schemas/ToolSource'
          description: 'When `valid`: which source the tool came from.'
        app_install_id:
          type: string
          description: 'When `valid` and `source === ''app''`: the app installation that provides the tool.'
        app_name:
          type: string
          description: 'When `valid` and `source === ''app''`: the app''s manifest name.'
        suggestion:
          type: string
          description: 'When `!valid` and a close match exists: the suggested replacement name (Levenshtein-based).'
        collisions:
          type: array
          items:
            type: object
            properties:
              source:
                $ref: '#/components/schemas/ToolSource'
              app_install_id:
                type: string
            required:
            - source
            additionalProperties: false
          description: Populated when a name appears in more than one source. Validation does not fail on this, but exposes the ambiguity so callers can surface a warning (last-write-wins resolution applies).
      required:
      - name
      - valid
      additionalProperties: false
      description: Per-name resolution result for `POST /tools/validate`.
    ValidateToolNamesPayload:
      type: object
      properties:
        names:
          type: array
          items:
            type: string
          description: Bare tool names as they appear in `agent_runner_options.tool_names`. `+`/`-` prefixes are stripped before lookup.
      required:
      - names
      additionalProperties: false
      description: Request payload for `POST /tools/validate`.
    ValidateToolNamesResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ToolValidationResult'
          description: One entry per requested name, in the same order.
        invalid_count:
          type: integer
          format: int32
          minimum: 0
          description: Convenience count of `results.filter(r => !r.valid).length`.
      required:
      - results
      - invalid_count
      additionalProperties: false
      description: Response from `POST /tools/validate`.
    ToolSource:
      type: string
      enum:
      - builtin
      - app
      - interaction
      description: 'Origin of a tool in the unified project-scoped tool registry.


        - `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills

        - `app`: tools contributed by an installed app for the project

        - `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`


        Skill semantics (the tool unlocks others when invoked) are NOT part of the source. They are identified universally by the `learn_` prefix in the tool name. This matches how the runtime registry stores them and avoids splitting one logical origin into two sources.'
    MCPToolAnnotations:
      type: object
      properties:
        title:
          type: string
          description: Human-readable display name for the tool
        readOnlyHint:
          type: boolean
          description: If true, the tool does not modify any state
        destructiveHint:
          type: boolean
          description: If true, the tool may perform irreversible destructive operations
        idempotentHint:
          type: boolean
          description: If true, calling the tool multiple times with the same args has no additional effect
        openWorldHint:
          type: boolean
          description: If true, the tool interacts with external entities outside the local environment
      additionalProperties: false
      description: Metadata hints from MCP tool annotations (per MCP spec).
    JSONSchema:
      type: object
      properties:
        type: {}
        description:
          type: string
        properties:
          $ref: '#/components/schemas/JSONSchemaProperties'
        items:
          $ref: '#/components/schemas/JSONSchema'
        format:
          type: string
        editor: {}
        default: {}
        additionalProperties:
          anyOf:
          - type: boolean
          - $ref: '#/components/schemas/JSONSchema'
        required:
          type: array
          items:
            type: string
    AggregatedToolArray:
      type: array
      items:
        $ref: '#/components/schemas/AggregatedTool'
    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
  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