Vertesia Files API

openapi: 3.2.0
info:
  title: Vertesia Files 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: Files
  description: File endpoints manage project-scoped object storage, including signed upload and download URLs, metadata updates, copies, and deletes.
paths:
  /files/metadata:
    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: GetFileMetadata
      tags:
      - Files
      summary: Get file metadata
      description: 'Retrieves metadata for a file by relative project path or fully qualified storage URI.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters:
      - name: file
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resolved file metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadataResponse'
        '404':
          description: The file does not exist.
        '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:
      - content:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: getMetadata
    put:
      operationId: SetFileMetadata
      tags:
      - Files
      summary: Set custom file metadata
      description: 'Applies custom metadata key-value pairs to a file in project storage.


        **Required permissions:** `content:write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      parameters: []
      responses:
        '200':
          description: Metadata update status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadataUpdateResult'
        '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:
      - content:write
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: setFileMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetFileMetadataPayload'
  /files/bucket:
    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: EnsureProjectFileBucket
      tags:
      - Files
      summary: Ensure the project file bucket exists
      description: 'Creates the project-scoped storage bucket when needed and returns its URI.


        **Required permissions:** `content:write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      parameters: []
      responses:
        '200':
          description: Project bucket URI.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileBucketResponse'
        '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:
      - content:write
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: createProjectBucket
  /files/upload-url:
    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: GetFileUploadUrl
      tags:
      - Files
      summary: Get a signed upload URL
      description: 'Generates a signed upload URL for a single file in the project bucket.


        **Required permissions:** `content:write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      parameters: []
      responses:
        '200':
          description: Signed upload URL metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFileUrlResponse'
        '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:
      - content:write
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: getUploadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUploadUrlPayload'
  /files/bulk-upload-urls:
    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: GetBulkFileUploadUrls
      tags:
      - Files
      summary: Get signed upload URLs for multiple files
      description: 'Generates signed upload URLs for a batch of files in a single request.


        **Required permissions:** `content:write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      parameters: []
      responses:
        '200':
          description: Signed upload URL metadata for each requested file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadUrlsResponse'
        '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:
      - content:write
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: getBulkUploadUrls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUploadUrlsPayload'
  /files/list:
    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: ListProjectFiles
      tags:
      - Files
      summary: List files by prefix
      description: 'Lists project-bucket file paths that match the supplied prefix.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters:
      - name: prefix
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Matching project file paths.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        '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:
      - content:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: listFiles
  /files/download-url:
    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: GetFileDownloadUrl
      tags:
      - Files
      summary: Get a signed download URL
      description: 'Generates a signed download URL for a file by relative path or fully qualified storage URI.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters: []
      responses:
        '200':
          description: Signed download URL metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFileUrlResponse'
        '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:
      - content:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: getDownloadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFileUrlPayload'
      x-vertesia-route-version: '20260210'
  /files/copy:
    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: CopyProjectFile
      tags:
      - Files
      summary: Copy a file
      description: 'Copies a file to a new destination within the same project bucket.


        **Required permissions:** `content:write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      parameters: []
      responses:
        '200':
          description: Copy operation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopyFileResponse'
        '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:
      - content:write
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: copyFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyFilePayload'
  /files/{path}:
    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
    delete:
      operationId: DeleteProjectFile
      tags:
      - Files
      summary: Delete a file or file prefix
      description: 'Deletes a single file or, with `prefix=true`, all files under the provided relative project path prefix.


        **Required permissions:** Any of `content:write`, `content:delete`, `content:superadmin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:write
      - OAuth2:
        - content:delete
      - OAuth2:
        - content:superadmin
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      - name: prefix
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFileResult'
        '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:
      - content:write
      - content:delete
      - content:superadmin
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/files.ts
        className: FilesResource
        methodName: deleteFile
components:
  schemas:
    DeleteFileResult:
      type: object
      properties:
        success:
          type: boolean
        count:
          type: number
        message:
          type: string
        file:
          type: string
      required:
      - success
      - count
      additionalProperties: false
    CopyFileResponse:
      type: object
      properties:
        success:
          type: boolean
        source:
          type: string
        dest:
          type: string
      required:
      - success
      - source
      - dest
      additionalProperties: false
    BulkUploadUrlsPayload:
      type: object
      properties:
        files:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              mime_type:
                type: string
              id:
                type: string
            required:
            - name
            additionalProperties: false
      required:
      - files
      additionalProperties: false
    GetUploadUrlPayload:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        mime_type:
          type: string
        ttl:
          type: number
      required:
      - name
      additionalProperties: false
    GetFileUrlPayload:
      type: object
      properties:
        file:
          type: string
        name:
          type: string
        disposition:
          type: string
          enum:
          - inline
          - attachment
      required:
      - file
      additionalProperties: false
    StringValueMap:
      type: object
      additionalProperties:
        type: string
    BulkUploadUrlsResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/GetFileUrlResponse'
      required:
      - files
      additionalProperties: false
    SetFileMetadataPayload:
      type: object
      properties:
        file:
          type: string
          description: The file path (relative to bucket) or full URI
        metadata:
          $ref: '#/components/schemas/StringValueMap'
          description: Custom metadata key-value pairs to set on the file
      required:
      - file
      - metadata
      additionalProperties: false
    FileMetadataResponse:
      type: object
      properties:
        name:
          type: string
        size:
          type: number
        contentType:
          type: string
        contentDisposition:
          type: string
        etag:
          type: string
        generation:
          type: string
        customMetadata:
          $ref: '#/components/schemas/StringValueMap'
      required:
      - name
      - size
      - contentType
      additionalProperties: false
    CopyFilePayload:
      type: object
      properties:
        source:
          type: string
        dest:
          type: string
      required:
      - source
      - dest
      additionalProperties: false
    FileMetadataUpdateResult:
      type: object
      properties:
        success:
          type: boolean
        file:
          type: string
      required:
      - success
      - file
      additionalProperties: false
    FileListResponse:
      type: object
      properties:
        files:
          type: array
          items:
            type: string
      required:
      - files
      additionalProperties: false
    FileBucketResponse:
      type: object
      properties:
        bucket:
          type: string
        location:
          type: string
      required:
      - bucket
      additionalProperties: false
    GetFileUrlResponse:
      type: object
      properties:
        url:
          type: string
        id:
          type: string
        mime_type:
          type: string
        path:
          type: string
      required:
      - url
      - id
      - path
      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
  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