Happyrobot Workflows API

openapi: 3.2.0
info:
  title: Happyrobot Public Workflows API
  description: Public API endpoints for Happyrobot
  version: 0.1.1
servers:
- url: https://platform.happyrobot.ai/api/v2
security:
- bearerAuth: []
tags:
- name: Workflows
paths:
  /workflows/:
    get:
      summary: List workflows
      tags:
      - Workflows
      description: Returns paginated workflows for the authenticated organization. Each workflow includes its latest version info (live production version preferred, otherwise most recent). Supports searching by name and filtering by folder.
      parameters:
      - schema:
          default: 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
        in: query
        name: page
        required: false
      - schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 100
        in: query
        name: page_size
        required: false
      - schema:
          default: desc
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort
        required: false
      - schema:
          type: string
        in: query
        name: search
        required: false
      - schema:
          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)$
        in: query
        name: folder_id
        required: false
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        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)$
                        org_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)$
                        name:
                          type: string
                        slug:
                          type: string
                        icon:
                          type:
                          - string
                          - 'null'
                        folder_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)$
                        data_retention_days:
                          type:
                          - number
                          - 'null'
                        timestamp:
                          type: string
                        latest_version:
                          type:
                          - object
                          - 'null'
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            slug:
                              type: string
                            version_number:
                              type:
                              - number
                              - 'null'
                            is_published:
                              type: boolean
                            is_live:
                              type: boolean
                            environment:
                              type: string
                            workflow_version:
                              description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).'
                              type: number
                            published_at:
                              type:
                              - string
                              - 'null'
                            timestamp:
                              type: string
                          required:
                          - id
                          - name
                          - slug
                          - is_published
                          - is_live
                          - timestamp
                          additionalProperties: false
                      required:
                      - id
                      - org_id
                      - name
                      - slug
                      - timestamp
                      - latest_version
                      additionalProperties: false
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      page_size:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      total_pages:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      total_records:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      has_next_page:
                        type: boolean
                      has_previous_page:
                        type: boolean
                    required:
                    - page
                    - page_size
                    - total_pages
                    - total_records
                    - has_next_page
                    - has_previous_page
                    additionalProperties: false
                required:
                - data
                - pagination
                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
        '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
    post:
      summary: Create a workflow
      tags:
      - Workflows
      description: 'Creates a new workflow in the authenticated organization. Supports three creation modes:


        1. **Plain** — Creates an empty workflow with an initial version.

        2. **From template** — Use `from_template` to create a pre-configured workflow with trigger and agent nodes. Available templates: `voice-agent`, `inbound-voice-agent`, `whatsapp-agent`, `sms-agent`, `email-agent`, `chatbot-agent`. Credentials are auto-discovered from the organization.

        3. **With version and nodes** — Use `version` to provide custom version metadata and an optional `nodes` array to define the workflow structure inline. The first node must be a `trigger`, subsequent nodes reference their parent via `parent_index`.


        `from_template` and `version` are mutually exclusive.


        Optionally, pass a `variables` array to create workflow-scoped environment variables alongside the workflow.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                icon:
                  default: robot
                  type: string
                folder_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)$
                settings:
                  type: object
                  properties:
                    data_retention_days:
                      type:
                      - integer
                      - 'null'
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    audits_enabled:
                      type: boolean
                    audit_sampling_bps:
                      type: integer
                      minimum: 0
                      maximum: 10000
                    audit_conditions:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                          title:
                            type: string
                          ors:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                ands:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      field:
                                        type: object
                                        properties:
                                          group_id:
                                            type: string
                                          variable_id:
                                            type: string
                                        required:
                                        - group_id
                                        - variable_id
                                      condition:
                                        type: string
                                      value:
                                        type: array
                                        items:
                                          description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                              required:
                              - ands
                          output:
                            type: array
                            items:
                              description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                    out_of_office_hours:
                      type: object
                      additionalProperties:
                        type: object
                        properties:
                          timezone:
                            type: string
                            minLength: 1
                          weekly_schedule:
                            minItems: 7
                            maxItems: 7
                            type: array
                            items:
                              type:
                              - array
                              - 'null'
                              items:
                                type:
                                - object
                                - 'null'
                                properties:
                                  start:
                                    type: string
                                    pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$
                                  end:
                                    type: string
                                    pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$
                                required:
                                - start
                                - end
                          off_days:
                            type: object
                            additionalProperties:
                              type: array
                              items:
                                type: object
                                properties:
                                  start:
                                    type: string
                                    pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$
                                  end:
                                    type: string
                                    pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$
                                required:
                                - start
                                - end
                        required:
                        - timezone
                        - weekly_schedule
                    webhooks:
                      type: array
                      items:
                        type: object
                        properties:
                          url:
                            type: string
                            format: uri
                          headers:
                            type: object
                            additionalProperties:
                              type: string
                        required:
                        - url
                    workflow_approval_process_settings:
                      type: object
                      properties:
                        environments:
                          type: object
                          properties:
                            production:
                              type: boolean
                            staging:
                              type: boolean
                            development:
                              type: boolean
                          required:
                          - production
                          - staging
                          - development
                      required:
                      - environments
                    deployment:
                      description: '@internal'
                      type: object
                      properties:
                        owner:
                          type:
                          - string
                          - 'null'
                          maxLength: 256
                        pod_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)$
                        category_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)$
                        stage_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)$
                        description:
                          type:
                          - string
                          - 'null'
                        linked_workflow_ids:
                          type:
                          - array
                          - 'null'
                          items:
                            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)$
                from_template:
                  oneOf:
                  - type: object
                    properties:
                      template:
                        type: string
                        enum:
                        - voice-agent
                      inputs:
                        default: {}
                        type: object
                        properties:
                          agent_name:
                            description: Display name for the AI voice agent.
                            type: string
                          prompt:
                            description: Prompt node overrides.
                            type: object
                            properties:
                              prompt_md:
                                description: Agent system prompt in markdown format.
                                type: string
                              initial_message:
                                description: The first message the agent says when the call/conversation starts.
                                type: string
                              initial_message_uninterruptible:
                                description: Whether the voice agent initial message is uninterruptible.
                                type: boolean
                              model:
                                description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).'
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - static
                                    - dynamic
                                  static:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                      description:
                                        type: string
                                    required:
                                    - id
                                    - name
                                  dynamic:
                                    type: array
                                    items:
                                      description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                                required:
                                - type
                    required:
                    - template
                  - type: object
                    properties:
                      template:
                        type: string
                        enum:
                        - inbound-voice-agent
                      inputs:
                        default: {}
                        type: object
                        properties:
                          agent_name:
                            description: Display name for the inbound voice agent.
                            type: string
                          prompt:
                            description: Prompt node overrides.
                            type: object
                            properties:
                              prompt_md:
                                description: Agent system prompt in markdown format.
                                type: string
                              initial_message:
                                description: The first message the agent says when the call/conversation starts.
                                type: string
                              initial_message_uninterruptible:
                                description: Whether the voice agent initial message is uninterruptible.
                                type: boolean
                              model:
                                description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).'
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - static
                                    - dynamic
                                  static:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                      description:
                                        type: string
                                    required:
                                    - id
                                    - name
                                  dynamic:
                                    type: array
                                    items:
                                      description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                                required:
                                - type
                    required:
                    - template
                  - type: object
                    properties:
                      template:
                        type: string
                        enum:
                        - whatsapp-agent
                      inputs:
                        default: {}
                        type: object
                        properties:
                          agent_name:
                            description: Display name for the WhatsApp agent.
                            type: string
                          prompt:
                            description: Prompt node overrides.
                            type: object
                            properties:
                              prompt_md:
                                description: Agent system prompt in markdown format.
                                type: string
                              initial_message:
                                description: The first message the agent says when the call/conversation starts.
                                type: string
                              initial_message_uninterruptible:
                                description: Whether the voice agent initial message is uninterruptible.
                                type: boolean
                              model:
                                description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).'
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - static
                                    - dynamic
                                  static:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                      description:
                                        type: string
                                    required:
                                    - id
                                    - name
                                  dynamic:
                                    type: array
                                    items:
                                      description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                                required:
                                - type
                    required:
                    - template
                  - type: object
                    properties:
                      template:
                        type: string
                        enum:
                        - sms-agent
                      inputs:
                        default: {}
                        type: object
                        properties:
                          agent_name:
                            description: Display name for the SMS agent.
                            type: string
                          prompt:
                            description: Prompt node overrides.
                            type: object
                            properties:
                              prompt_md:
                                description: Agent system prompt in markdown format.
                                type: string
                              initial_message:
                                description: The first message the agent says when the call/conversation starts.
                                type: string
                              initial_message_uninterruptible:
                                description: Whether the voice agent initial message is uninterruptible.
                                type: boolean
                              model:
                                description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).'
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - static
                                    - dynamic
                                  static:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                      description:
                                        type: string
                                    required:
                                    - id
                                    - name
                                  dynamic:
                                    type: array
                                    items:
                                      description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}'
                                required:
                                - type
                    required:
                    - template
                  - type: object
                    properties:
                      template:
                        type: string
                        enum:
                        - email-agent
                      inputs:
                        default: {}
                        type: object
                        properties:
                          agent_name:
                            description: Display name for the Email agent.
                            type: string
                          email_to:
                            description: Default recipient email address.
                            type: string
                          prompt:
                            description: Prompt node overrides.
                            type: object
                            properties:
                              prompt_md:
                                description: Agent system prompt in markdown format.
                                type: string
                              initial_message:
                                description: The first message the agent says when the call/conversation starts.
                                type: string
                              initial_message_uninterruptible:
                                description: Whether the voice agent initial message is uninterruptible.
                                type: boolean
                              model:
                                description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).'
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - static
                                    - dynamic
                                  static:
                                    type: object
                                    properties:


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