Happyrobot Versions API

openapi: 3.2.0
info:
  title: Happyrobot Versions API
  version: '1.0'
  description: 'Operations tagged Versions across 2 of this provider''s published API definitions: happyrobot-platform-v1-openapi.json, happyrobot-public-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://platform.happyrobot.ai/api/v1
- url: https://platform.happyrobot.ai/api/v2
tags:
- name: Versions
paths:
  /versions:
    get:
      description: Get all workflow versions for a given use case
      summary: Get workflow versions
      tags:
      - Versions
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      - name: use_case_id
        in: query
        description: The ID of the use case.
        required: true
        schema:
          type: string
      - name: with_changelog
        in: query
        description: Whether to include the changelog.
        schema:
          default: false
          type:
          - boolean
          - 'null'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    slug:
                      type: string
                      maxLength: 256
                    org_id:
                      type: string
                      format: uuid
                    use_case_id:
                      type: string
                      format: uuid
                    version_number:
                      type:
                      - number
                      - 'null'
                    name:
                      type: string
                      maxLength: 256
                    is_published:
                      type: boolean
                    is_live:
                      type: boolean
                    environment:
                      type: string
                      enum:
                      - staging
                      - production
                    source_version_id:
                      type:
                      - string
                      - 'null'
                      format: uuid
                    timestamp:
                      type: string
                      format: date-time
                    published_at:
                      type:
                      - string
                      - 'null'
                      format: date-time
                    is_deleted:
                      type: boolean
                    description:
                      type:
                      - string
                      - 'null'
                    created_by:
                      type:
                      - string
                      - 'null'
                      format: uuid
                    changelog:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        version_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        created_at:
                          type: string
                          format: date-time
                        type:
                          type: string
                          enum:
                          - fork
                          - publish
                          - unpublish
                          - unlock
                          - workflow_update
                          - delete
                          - misc
                        description:
                          type:
                          - string
                          - 'null'
                        created_by:
                          type:
                          - string
                          - 'null'
                          format: uuid
                      required:
                      - id
                      - version_id
                      - created_at
                      - type
                      - description
                      - created_by
                  required:
                  - id
                  - slug
                  - org_id
                  - use_case_id
                  - version_number
                  - name
                  - is_published
                  - is_live
                  - environment
                  - source_version_id
                  - timestamp
                  - published_at
                  - is_deleted
                  - description
                  - created_by
                description: A list of workflow versions.
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
    servers:
    - url: https://platform.happyrobot.ai/api/v1
  /versions/{version_id}:
    get:
      description: Get a workflow version by ID
      summary: Get a workflow version
      tags:
      - Versions
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the workflow version.
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  slug:
                    type: string
                    maxLength: 256
                  org_id:
                    type: string
                    format: uuid
                  use_case_id:
                    type: string
                    format: uuid
                  version_number:
                    type:
                    - number
                    - 'null'
                  name:
                    type: string
                    maxLength: 256
                  is_published:
                    type: boolean
                  is_live:
                    type: boolean
                  environment:
                    type: string
                    enum:
                    - staging
                    - production
                  source_version_id:
                    type:
                    - string
                    - 'null'
                    format: uuid
                  timestamp:
                    type: string
                    format: date-time
                  published_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  is_deleted:
                    type: boolean
                  description:
                    type:
                    - string
                    - 'null'
                  created_by:
                    type:
                    - string
                    - 'null'
                    format: uuid
                  changelog:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        version_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        created_at:
                          type: string
                          format: date-time
                        type:
                          type: string
                          enum:
                          - fork
                          - publish
                          - unpublish
                          - unlock
                          - workflow_update
                          - delete
                          - misc
                        description:
                          type:
                          - string
                          - 'null'
                        created_by:
                          type:
                          - string
                          - 'null'
                          format: uuid
                      required:
                      - id
                      - version_id
                      - created_at
                      - type
                      - description
                      - created_by
                    description: The changelog for the version.
                required:
                - id
                - slug
                - org_id
                - use_case_id
                - version_number
                - name
                - is_published
                - is_live
                - environment
                - source_version_id
                - timestamp
                - published_at
                - is_deleted
                - description
                - created_by
                - changelog
                description: A workflow version.
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
    servers:
    - url: https://platform.happyrobot.ai/api/v1
  /versions/{version_id}/:
    get:
      summary: Get a version with nodes summary
      tags:
      - Versions
      description: Returns a single version by UUID or slug with metadata, node count, node counts by type, and the list of events (action node types) used.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: version_id
        required: true
        description: Version UUID or slug
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  workflow_slug:
                    type: string
                  version_number:
                    type:
                    - number
                    - 'null'
                  is_published:
                    type: boolean
                  is_live:
                    type: boolean
                  environment:
                    type: string
                  workflow_version:
                    type: number
                  published_at:
                    type:
                    - string
                    - 'null'
                  timestamp:
                    type: string
                  node_count:
                    type: number
                  node_counts_by_type:
                    type: object
                    additionalProperties:
                      type: number
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id:
                          type: string
                        name:
                          type: string
                      required:
                      - event_id
                      - name
                      additionalProperties: false
                  changelog:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                        description:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                        created_by:
                          type:
                          - object
                          - 'null'
                          properties:
                            type:
                              type: string
                              enum:
                              - user
                              - api_key
                            name:
                              type:
                              - string
                              - 'null'
                          required:
                          - type
                          - name
                          additionalProperties: false
                      required:
                      - id
                      - type
                      - description
                      - created_at
                      - created_by
                      additionalProperties: false
                required:
                - id
                - name
                - slug
                - is_published
                - is_live
                - timestamp
                - node_count
                - node_counts_by_type
                - events
                - changelog
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
    patch:
      summary: Update a version
      tags:
      - Versions
      description: Updates version metadata (name and/or description). Accepts a version UUID or slug as the path parameter.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Version display name
                  type: string
                  minLength: 1
                  maxLength: 256
                description:
                  description: Version description
                  type: string
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: version_id
        required: true
        description: Version UUID or slug
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  workflow_slug:
                    type: string
                  version_number:
                    type:
                    - number
                    - 'null'
                  is_published:
                    type: boolean
                  is_live:
                    type: boolean
                  environment:
                    type: string
                  workflow_version:
                    type: number
                  published_at:
                    type:
                    - string
                    - 'null'
                  timestamp:
                    type: string
                  description:
                    type:
                    - string
                    - 'null'
                required:
                - id
                - name
                - slug
                - is_published
                - is_live
                - timestamp
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
    servers:
    - url: https://platform.happyrobot.ai/api/v2
  /versions/{version_id}/fork:
    post:
      summary: Fork a version
      tags:
      - Versions
      description: Creates a new version by copying all nodes from the specified version. The new version gets the next available version number and is unlocked/unpublished. If the source uses workflow engine v2, the fork remains an editable v2 draft and cannot be published through the public API until upgraded to v3. Any existing published v2 version remains live and continues running until explicitly unpublished. Accepts a version UUID or slug as the path parameter.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: version_id
        required: true
        description: Version UUID or slug
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  workflow_slug:
                    type: string
                  version_number:
                    type:
                    - number
                    - 'null'
                  is_published:
                    type: boolean
                  is_live:
                    type: boolean
                  environment:
                    type: string
                  workflow_version:
                    type: number
                  published_at:
                    type:
                    - string
                    - 'null'
                  timestamp:
                    type: string
                  description:
                    type:
                    - string
                    - 'null'
                  source_version_id:
                    type:
                    - string
                    - 'null'
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  warnings:
                    type: array
                    items:
                      type: string
                required:
                - id
                - name
                - slug
                - is_published
                - is_live
                - timestamp
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
    servers:
    - url: https://platform.happyrobot.ai/api/v2
  /versions/{version_id}/publish:
    post:
      summary: Publish a version
      tags:
      - Versions
      description: 'Publishes the specified version to make it live. Before publishing, node configuration completeness is validated. If untested nodes exist, a synchronous test-all is triggered automatically. Test errors do not block publishing (matching UI behavior) but are returned as informational warnings in the `test_errors` field. Workflow engine v2 versions cannot be published through the public API. Existing published v2 versions remain live and continue running until explicitly unpublished; this endpoint does not stop them.


        For an eligible v3 target, either `unpublish_version_id` or `force: true` must be provided when a live version exists. Use `unpublish_version_id` to explicitly specify the live version to replace. Use `force: true` to automatically unpublish whatever version is currently live.'
      requestBody:
        content:
          application/json:
            schema:
              type:
              - object
              - 'null'
              properties:
                unpublish_version_id:
                  description: ID of the currently live version to unpublish before publishing this one. Required when the workflow already has a live version, unless force is true.
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                environment:
                  default: production
                  description: Target environment for publishing
                  type: string
                  enum:
                  - production
                  - staging
                  - development
                force:
                  default: false
                  description: When true, automatically unpublishes any currently live version without requiring unpublish_version_id.
                  type: boolean
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: version_id
        required: true
        description: Version UUID or slug
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  is_published:
                    type: boolean
                  is_live:
                    type: boolean
                  environment:
                    type: string
                  missing_variables:
                    description: Variable references that could not be resolved against upstream nodes. Informational — does not block publishing.
                    type: array
                    items:
                      type: object
                      properties:
                        node_id:
                          type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          description: The node containing the broken reference
                        node_name:
                          description: Display name of the node
                          type:
                          - string
                          - 'null'
                        missing_variables:
                          type: array
                          items:
                            type: object
                            properties:
                              group_id:
                                type: string
                                description: The referenced variable group ID (persistent_id of the source node)
                              variable_id:
                                type: string
                                description: The referenced variable ID within the group
                            required:
                            - group_id
                            - variable_id
                            additionalProperties: false
                          description: Variable references that could not be resolved
                      required:
                      - node_id
                      - node_name
                      - missing_variables
                      additionalProperties: false
                  test_errors:
                    description: Nodes with test errors at time of publishing. Informational — does not block publishing (matches UI behavior).
                    type: array
                    items:
                      type: object
                      properties:
                        node_id:
                          type: string
                        name:
                          type:
                          - string
                          - 'null'
                        error:
                          type: string
                      required:
                      - node_id
                      - name
                      - error
                      additionalProperties: false
                required:
                - id
                - is_published
                - is_live
                - environment
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        node_id:
                          type: string
                        name:
                          type:
                          - string
                          - 'null'
                        error:
                          type: string
                      required:
                      - node_id
                      - name
                      - error
                      additionalProperties: false
                  missing_variables:
                    description: Variable references that could not be resolved against upstream nodes.
                    type: array
                    items:
                      type: object
                      properties:
                        node_id:
                          type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          description: The node containing the broken reference
                        node_name:
                          description: Display name of the node
                          type:
                          - string
                          - 'null'
                        missing_variables:
                          type: array


# --- truncated at 32 KB (285 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/happyrobot/refs/heads/main/openapi/happyrobot-versions-api-openapi.yml