openapi: 3.1.0
info:
  description: Workflow management API for B3OS
  title: B3OS Workflow Action seo API
  version: '1.0'
tags:
- name: seo
paths:
  /v1/seo/pages:
    get:
      description: List all published SEO integration pages with pagination
      parameters:
      - description: 'Filter by page type: single or combo'
        in: query
        name: page_type
        schema:
          type: string
      - description: 'Maximum number of pages (default: 100, max: 1000)'
        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:
                $ref: '#/components/schemas/ListSeoPagesSuccessResponse'
          description: OK
        '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
      tags:
      - seo
  /v1/seo/pages/bulk-upsert:
    post:
      description: Bulk upsert SEO integration pages (used by CI/CD build script)
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/BulkUpsertSeoPagesParams'
                summary: body
                description: Pages to upsert
        description: Pages to upsert
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertSeoPagesSuccessResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Bad Request
        '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
      tags:
      - seo
  /v1/seo/pages/generate:
    post:
      description: Trigger SEO page generation (admin only).
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/GenerateSeoPagesParams'
                summary: body
                description: Generation parameters
        description: Generation parameters
        required: true
      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: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: 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
      tags:
      - seo
  /v1/seo/pages/{slug}:
    get:
      description: Get a single SEO integration page by slug
      parameters:
      - description: Page slug (e.g. airtable or airtable-and-polymarket)
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSeoPageSuccessResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Not Found
        '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
      tags:
      - seo
    put:
      description: Update a SEO integration page by slug (admin only)
      parameters:
      - description: Page slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/UpdateSeoPageParams'
                summary: body
                description: Fields to update
        description: Fields to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSeoPageSuccessResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Not Found
        '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
      tags:
      - seo
components:
  schemas:
    BulkUpsertSeoPagesParams:
      properties:
        pages:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoIntegrationPage'
          type: array
          uniqueItems: false
      required:
      - pages
      type: object
    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
    BulkUpsertResultData:
      properties:
        totalReceived:
          type: integer
        upsertedCount:
          type: integer
      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_pkg_entity.SeoIntegrationPage:
      properties:
        appSlugs:
          items:
            type: string
          type: array
          uniqueItems: false
        contentStatus:
          type: string
        createdAt:
          description: Timestamps.
          type: string
        faqs:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoFAQ'
          type: array
          uniqueItems: false
        heroDescription:
          description: AI-generated content.
          type: string
        id:
          type: string
        integrationStatus:
          description: Status tracking.
          type: string
        isPublished:
          type: boolean
        keywords:
          items:
            type: string
          type: array
          uniqueItems: false
        metaDescription:
          type: string
        pageType:
          type: string
        requestCount:
          type: integer
        slug:
          type: string
        title:
          description: SEO metadata.
          type: string
        updatedAt:
          type: string
        useCases:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoUseCase'
          type: array
          uniqueItems: false
      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
    UpdateSeoPageSuccessResponse:
      properties:
        code:
          example: 200
          type: integer
        data:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoIntegrationPage'
        message:
          example: success
          type: string
        requestId:
          example: abc-123
          type: string
      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
    ListSeoPagesSuccessResponse:
      properties:
        code:
          example: 200
          type: integer
        data:
          $ref: '#/components/schemas/ListSeoPagesData'
        message:
          example: success
          type: string
        requestId:
          example: abc-123
          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
    GetSeoPageSuccessResponse:
      properties:
        code:
          example: 200
          type: integer
        data:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoIntegrationPage'
        message:
          example: success
          type: string
        requestId:
          example: abc-123
          type: string
      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
    ListSeoPagesData:
      properties:
        pages:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoIntegrationPage'
          type: array
          uniqueItems: false
        total:
          type: integer
      type: object
    UpdateSeoPageParams:
      properties:
        faqs:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoFAQ'
          type: array
          uniqueItems: false
        heroDescription:
          type: string
        isPublished:
          type: boolean
        keywords:
          items:
            type: string
          type: array
          uniqueItems: false
        metaDescription:
          type: string
        title:
          type: string
        useCases:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoUseCase'
          type: array
          uniqueItems: false
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoUseCase:
      properties:
        description:
          type: string
        title:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.SeoFAQ:
      properties:
        answer:
          type: string
        question:
          type: string
      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
    GenerateSeoPagesParams:
      properties:
        dryRun:
          type: boolean
        regenerate:
          type: boolean
        skipAI:
          type: boolean
      type: object
    BulkUpsertSeoPagesSuccessResponse:
      properties:
        code:
          example: 200
          type: integer
        data:
          $ref: '#/components/schemas/BulkUpsertResultData'
        message:
          example: success
          type: string
        requestId:
          example: abc-123
          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