openapi: 3.1.0
info:
  description: Workflow management API for B3OS
  title: B3OS Workflow Action workflow-templates API
  version: '1.0'
tags:
- name: workflow-templates
paths:
  /v1/organizations/{orgId}/templates/public:
    get:
      description: 'Retrieve all public templates for a specific organization (no authentication required)

        This endpoint is used for organization detail pages to showcase public templates'
      parameters:
      - description: Organization ID
        in: path
        name: orgId
        required: true
        schema:
          type: string
      - description: Number of items (default 20, max 100)
        in: query
        name: limit
        schema:
          type: integer
      - description: Offset for pagination (default 0)
        in: query
        name: offset
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  code:
                    type: integer
                  data: {}
                  message:
                    type: string
                  requestId:
                    type: string
                type: object
          description: Public templates for organization
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Internal server error
      summary: List public templates by organization
      tags:
      - workflow-templates
  /v1/templates/{templateId}:
    get:
      description: 'Retrieve a template by ID with authorization (public templates or user''s org templates)

        No authentication required for public templates. Authenticated users can access their org''s templates.'
      parameters:
      - description: Template ID
        in: path
        name: templateId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  code:
                    type: integer
                  data: {}
                  message:
                    type: string
                  requestId:
                    type: string
                type: object
          description: Template details
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Template not found or unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Internal server error
      summary: Get template by ID
      tags:
      - workflow-templates
components:
  schemas:
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference:
      description: nil if action doesn't need connector
      properties:
        id:
          description: Connector ID (or subOrgId for turnkey)
          type: string
        type:
          description: Connector type (e.g., "slack", "turnkey")
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.NodePosition:
      properties:
        x:
          type: number
        y:
          type: number
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput:
      properties:
        description:
          type: string
        key:
          type: string
        required:
          type: boolean
        type:
          description: '"string", "number", "boolean", "object", "array"'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.CommentReply:
      properties:
        createdAt:
          type: string
        createdBy:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteUser'
        id:
          type: string
        text:
          type: string
        updatedAt:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode:
      properties:
        branch:
          description: '"then" or "else", only when parent is "if" node'
          type: string
        children:
          items:
            type: string
          type: array
          uniqueItems: false
        connector:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference'
        description:
          description: AI-generated 1-sentence description
          type: string
        loopBody:
          description: Loop body nodes (only for for-each nodes)
          items:
            type: string
          type: array
          uniqueItems: false
        payload:
          additionalProperties: {}
          type: object
        resultSchema:
          additionalProperties: {}
          description: 'ResultSchema describes the output structure of this node (populated dynamically for x402 endpoints).

            This is used by the frontend to show available output variables in the variable picker.'
          type: object
        titleOverride:
          description: AI-generated short title (2-6 words), only when more descriptive than default
          type: string
        type:
          type: string
      required:
      - payload
      - type
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Comment:
      properties:
        createdAt:
          type: string
        createdBy:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteUser'
        id:
          type: string
        nodeId:
          type: string
        position:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.NodePosition'
        replies:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.CommentReply'
          type: array
          uniqueItems: false
        resolved:
          type: boolean
        text:
          type: string
        updatedAt:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse:
      properties:
        code:
          type: integer
        details:
          items: {}
          type: array
          uniqueItems: false
        message:
          type: string
        requestId:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.PropSchema:
      properties:
        chainPropKey:
          description: 'For tokenSelector: prop key providing chainId'
          type: string
        enum:
          items: {}
          type: array
          uniqueItems: false
        enumLabels:
          items:
            type: string
          type: array
          uniqueItems: false
        inputType:
          description: 'InputType is a UI rendering hint. The frontend uses it to pick a rich

            selector component instead of a plain text input. Unknown values are

            silently ignored (falls back to default input).

            Valid values: chainSelector, tokenSelector, address, recipientAddress, email'
          type: string
        maximum:
          type: number
        minimum:
          type: number
        pattern:
          type: string
        placeholder:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNote:
      properties:
        color:
          type: string
        createdAt:
          type: string
        createdBy:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteUser'
        id:
          type: string
        position:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.NodePosition'
        size:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteSize'
        text:
          type: string
        updatedAt:
          type: string
        zIndex:
          type: integer
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.TemplateVisibility:
      enum:
      - org
      - public
      - org
      - public
      type: string
      x-enum-comments:
        TemplateVisibilityOrg: Only visible to organization members
        TemplateVisibilityPublic: Visible to everyone
      x-enum-varnames:
      - TemplateVisibilityOrg
      - TemplateVisibilityPublic
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteUser:
      properties:
        clientId:
          type: string
        name:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Template:
      properties:
        archived:
          type: boolean
        category:
          description: 'Deprecated: Use Tags instead'
          type: string
        cooldownMs:
          type: integer
        createdAt:
          type: string
        createdBy:
          type: string
        definition:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition'
        description:
          type: string
        forkCount:
          type: integer
        id:
          type: string
        isPromoted:
          type: boolean
        maxRuns:
          type: integer
        name:
          type: string
        organizationDescription:
          type: string
        organizationId:
          description: Fields for user-generated templates (nil for built-in templates)
          type: string
        organizationName:
          type: string
        organizationPhoto:
          type: string
        promotedAt:
          type: string
        promotedBy:
          type: string
        sourceWorkflowId:
          description: Source workflow link (nil for built-in or legacy templates)
          type: string
        tags:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Tag'
          type: array
          uniqueItems: false
        templateProps:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.TemplateProp'
          type: array
          uniqueItems: false
        uiMetadata:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowUIMetadata'
        updatedAt:
          type: string
        updatedBy:
          type: string
        version:
          type: integer
        visibility:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.TemplateVisibility'
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowUIMetadata:
      properties:
        comments:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Comment'
          type: array
          uniqueItems: false
        nodePositions:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.NodePosition'
          type: object
        stickyNotes:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNote'
          type: array
          uniqueItems: false
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition:
      description: 'Definition is the full workflow graph to execute. Must contain a

        "root" node with type "manual". All action nodes referenced in

        children arrays must be present.'
      properties:
        inputSchema:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput'
          type: array
          uniqueItems: false
        nodes:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode'
          type: object
        sensitivePropKeys:
          items:
            type: string
          type: array
          uniqueItems: false
      required:
      - nodes
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.TemplateProp:
      properties:
        default: {}
        description:
          type: string
        key:
          type: string
        name:
          type: string
        properties:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.PropSchema'
        required:
          type: boolean
        sensitive:
          type: boolean
        type:
          description: '"string", "number", "integer", "boolean"'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.StickyNoteSize:
      properties:
        height:
          type: number
        width:
          type: number
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Tag:
      properties:
        categories:
          description: e.g., ["blockchain", "finance"]
          items:
            type: string
          type: array
          uniqueItems: false
        count:
          description: 'Scope-dependent: template, action, trigger, or connector count'
          type: integer
        createdAt:
          type: string
        description:
          type: string
        id:
          type: string
        imageUrl:
          type: string
        name:
          type: string
        promotedTemplateCount:
          type: integer
        publicTemplateCount:
          type: integer
        slug:
          type: string
        updatedAt:
          type: string
        weight:
          description: Higher weight = more prominent
          type: integer
      type: object
    ? github_com_b3-fun_b3-mono_services_b3os-workflow_PaginatedData-github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity_Template
    : properties:
        hasMore:
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Template'
          type: array
          uniqueItems: false
        limit:
          type: integer
        offset:
          type: integer
      type: object
    data:
      properties:
        data:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_PaginatedData-github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity_Template'
      type: object