Vertesia Rendering API

openapi: 3.2.0
info:
  title: Vertesia Rendering 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: Rendering
  description: Rendering endpoints convert markdown content or stored objects into rendered artifacts such as PDF and DOCX files through asynchronous workflows.
paths:
  /rendering/jobs:
    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: CreateRenderingJob
      tags:
      - Rendering
      summary: Create a rendering job
      description: 'Starts an asynchronous markdown rendering workflow for PDF or DOCX output.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters: []
      responses:
        '200':
          description: Started rendering workflow metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderMarkdownStartResponse'
        '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/rendering.ts
        className: RenderingResource
        methodName: startRenderingJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderMarkdownPayload'
  /rendering/jobs/status:
    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: GetRenderingJobStatus
      tags:
      - Rendering
      summary: Get rendering job status
      description: 'Retrieves workflow status for a markdown rendering job and returns a download URL when complete.


        **Required permissions:** `content:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - content:read
      parameters:
      - name: workflow_id
        in: query
        required: true
        schema:
          type: string
      - name: workflow_run_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rendering job status and output metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderMarkdownStatusResponse'
        '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/rendering.ts
        className: RenderingResource
        methodName: getRenderingJobStatus
components:
  schemas:
    RenderMarkdownStatusResponse:
      type: object
      properties:
        workflow_id:
          type:
          - string
          - 'null'
        workflow_run_id:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/WorkflowExecutionStatus'
        format:
          $ref: '#/components/schemas/MarkdownRenditionFormat'
          description: Requested output format (if known)
        download_url:
          type: string
          description: Download URL for completed output
        file_uri:
          type: string
          description: File URI in storage for completed output
        error:
          type: string
          description: Error details for failed/terminated runs
      required:
      - workflow_id
      - workflow_run_id
      - status
      additionalProperties: false
      description: Polled status response for markdown rendering workflow.
    WorkflowExecutionStatus:
      type: number
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
    RenderMarkdownPayload:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/MarkdownRenditionFormat'
          description: Output format
        object_id:
          type: string
          description: Object ID to render (mutually exclusive with content)
        content:
          type: string
          description: Inline markdown content to render (mutually exclusive with object_id)
        title:
          type: string
          description: Document title (used for filename when using inline content)
        template_url:
          type: string
          description: URL to a template file for pandoc (DOCX reference doc or LaTeX template)
        template_logo_url:
          type: string
          description: Optional logo URL for template variable `logo-path` (studio-hosted URL)
        template_path:
          type: string
          description: 'Template file via artifact:/store: protocol (takes precedence over template_url)'
        logo_path:
          type: string
          description: 'Logo file via artifact:/store: protocol (takes precedence over template_logo_url)'
        use_default_template:
          type: boolean
          description: 'Use Vertesia default template if no template_url provided (default: true for pdf)'
        pandoc_options:
          type: array
          items:
            type: string
          description: Additional pandoc command-line options
        artifact_run_id:
          type: string
          description: 'Run ID for resolving artifact: and image: URLs'
        metadata:
          $ref: '#/components/schemas/PdfRenderingMetadata'
          description: Document metadata for PDF footer/header
        template_data_source:
          type: string
          description: 'Source reference for auto-wired template data: `store:<objectId>` or `artifact:<path-to-json>`'
        output_path:
          type: string
          description: Custom upload path for the rendered output
      required:
      - format
      additionalProperties: false
      description: Payload for rendering markdown to PDF or DOCX. Either object_id OR content must be provided.
    MarkdownRenditionFormat:
      type: string
      enum:
      - docx
      - pdf
    RenderMarkdownStartResponse:
      type: object
      properties:
        workflow_id:
          type:
          - string
          - 'null'
        workflow_run_id:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/WorkflowExecutionStatus'
        format:
          $ref: '#/components/schemas/MarkdownRenditionFormat'
          description: Requested output format
      required:
      - workflow_id
      - workflow_run_id
      - status
      - format
      additionalProperties: false
      description: Initial response when starting a markdown rendering workflow. Clients should poll status using workflow_id/workflow_run_id.
    PdfRenderingMetadata:
      type: object
      properties:
        document_id:
          type: string
          description: Document ID to display in footer
        agent_name:
          type: string
          description: Agent name that generated the document
        agent_run_id:
          type: string
          description: Agent run ID to display in footer
        subtitle:
          type: string
          description: Document subtitle
        author:
          type: array
          items:
            type: string
          description: Document author(s)
        date:
          type: string
          description: Document date (displayed in header and title page; defaults to today if omitted)
      additionalProperties: false
      description: Metadata for PDF rendering (displayed in header/footer)
    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