components:
  schemas:
    AccountingContact:
      properties:
        contact_type:
          enum:
          - customer
          - supplier
          - both
          type: string
        currency:
          type: string
        email:
          nullable: true
          type: string
        id:
          type: integer
        is_active:
          type: boolean
        name:
          type: string
        phone:
          nullable: true
          type: string
      type: object
    Asset:
      properties:
        asset_type:
          enum:
          - image
          - video
          - audio
          - document
          - other
          example: document
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        file_size:
          description: Size in bytes
          type: integer
        folder_id:
          nullable: true
          type: integer
        is_primary_language:
          description: True if this is the canonical variant in its language group
          type: boolean
        language_group_id:
          description: Language group this asset belongs to, if any
          nullable: true
          type: integer
        mime_type:
          example: application/pdf
          type: string
        permission:
          description: Access control level
          enum:
          - private
          - team
          - public
          type: string
        primary_language:
          description: BCP-47 locale code of this file
          example: en-US
          nullable: true
          type: string
        serve_token:
          description: Token for public delivery URL
          type: string
        serve_url:
          description: Public delivery URL (if permission allows)
          type: string
        tags:
          example:
          - logo
          - brand
          items:
            type: string
          type: array
        title:
          example: Brand Guide 2025.pdf
          type: string
        uid:
          example: ast_7f3c2a
          type: string
        updated_at:
          format: date-time
          type: string
        version:
          example: 1
          type: integer
      type: object
    AssetFolder:
      properties:
        asset_count:
          type: integer
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        name:
          example: Brand Guidelines
          type: string
        parent_id:
          nullable: true
          type: integer
      type: object
    AssetInput:
      properties:
        description:
          type: string
        folder_id:
          nullable: true
          type: integer
        permission:
          enum:
          - private
          - team
          - public
          type: string
        primary_language:
          description: BCP-47 locale code
          example: en-US
          type: string
        tags:
          items:
            type: string
          type: array
        title:
          type: string
        version_label:
          description: Label for this version snapshot
          type: string
        version_notes:
          description: Change notes for this version snapshot
          type: string
      type: object
    AssetLanguageGroup:
      properties:
        id:
          type: integer
        variants:
          items:
            properties:
              is_primary:
                type: boolean
              primary_language:
                example: en-US
                type: string
              title:
                type: string
              uid:
                type: string
            type: object
          type: array
      type: object
    AssetVersion:
      properties:
        created_at:
          format: date-time
          type: string
        file_size:
          type: integer
        id:
          type: integer
        mime_type:
          example: application/pdf
          type: string
        version:
          example: 3
          type: integer
        version_label:
          example: Final approved
          nullable: true
          type: string
        version_notes:
          example: Updated logo colours
          nullable: true
          type: string
      type: object
    Bill:
      properties:
        balance_due:
          type: number
        bill_number:
          type: string
        contact_id:
          nullable: true
          type: integer
        currency:
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        id:
          type: integer
        issue_date:
          format: date
          type: string
        status:
          enum:
          - draft
          - awaiting_payment
          - paid
          - voided
          type: string
        total:
          type: number
      type: object
    CalendarBooking:
      properties:
        created_at:
          format: date-time
          type: string
        end_time:
          format: date-time
          type: string
        event_type_id:
          type: integer
        id:
          type: integer
        invitee_email:
          format: email
          type: string
        invitee_name:
          type: string
        location:
          nullable: true
          type: string
        notes:
          nullable: true
          type: string
        start_time:
          format: date-time
          type: string
        status:
          enum:
          - confirmed
          - cancelled
          - no_show
          - rescheduled
          type: string
        video_conf_link:
          nullable: true
          type: string
      type: object
    CalendarEventType:
      properties:
        booking_url:
          example: /book/abc123
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        duration_mins:
          example: 30
          type: integer
        id:
          type: integer
        is_active:
          type: boolean
        location_type:
          enum:
          - video
          - phone
          - in_person
          - custom
          type: string
        name:
          example: 30-min Intro Call
          type: string
        slug:
          type: string
      type: object
    CalendarEventTypeInput:
      properties:
        description:
          type: string
        duration_minutes:
          example: 30
          type: integer
        location:
          default: video
          description: video|phone|in_person or custom text
          type: string
        name:
          example: 30-min Intro Call
          type: string
      required:
      - name
      - duration_minutes
      type: object
    Community:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_active:
          type: boolean
        member_count:
          type: integer
        name:
          type: string
        post_count:
          type: integer
        privacy:
          enum:
          - public
          - private
          - secret
          type: string
        slug:
          type: string
        tagline:
          nullable: true
          type: string
      type: object
    CommunityMember:
      properties:
        email:
          format: email
          nullable: true
          type: string
        id:
          type: integer
        joined_at:
          format: date-time
          nullable: true
          type: string
        name:
          type: string
        role:
          enum:
          - admin
          - moderator
          - member
          type: string
        status:
          enum:
          - active
          - banned
          - pending
          type: string
      type: object
    CommunityPost:
      properties:
        author_id:
          nullable: true
          type: integer
        body:
          nullable: true
          type: string
        community_id:
          type: integer
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_pinned:
          type: boolean
        space_id:
          nullable: true
          type: integer
        title:
          type: string
        view_count:
          type: integer
      type: object
    CommunityPostInput:
      properties:
        body:
          type: string
        space_id:
          description: Space (channel) to post in
          nullable: true
          type: integer
        title:
          type: string
      required:
      - title
      type: object
    CreatorAsset:
      properties:
        asset_type:
          example: blog_post
          type: string
        audience:
          nullable: true
          type: string
        brief:
          nullable: true
          type: string
        campaign_id:
          format: uuid
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        plain_text_preview:
          nullable: true
          type: string
        status:
          enum:
          - draft
          - generating
          - ready
          - published
          - archived
          type: string
        title:
          example: Q2 Product Update
          type: string
        tone:
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
        version:
          type: integer
        word_count:
          nullable: true
          type: integer
      type: object
    CreatorAssetInput:
      properties:
        asset_type:
          description: blog_post | email | social_post | document | web_page | press_release
            | newsletter | case_study | product_description | landing_page | wiki_article
            | help_article
          example: blog_post
          type: string
        audience:
          example: SMB decision-makers
          type: string
        brief:
          description: AI generation brief / outline
          type: string
        campaign_id:
          format: uuid
          type: string
        generate:
          default: true
          description: Trigger AI content generation on creation
          type: boolean
        title:
          example: Q2 Product Update
          type: string
        tone:
          example: professional
          type: string
      required:
      - asset_type
      - title
      type: object
    CreatorCampaign:
      properties:
        asset_count:
          type: integer
        brief:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        name:
          example: Spring Launch 2026
          type: string
        status:
          enum:
          - active
          - completed
          - archived
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    CreatorCampaignInput:
      properties:
        brief:
          type: string
        name:
          example: Spring Launch 2026
          type: string
      required:
      - name
      type: object
    CreatorSchedule:
      properties:
        asset_id:
          format: uuid
          type: string
        asset_title:
          type: string
        content_mode:
          enum:
          - current
          - regenerate
          type: string
        created_at:
          format: date-time
          type: string
        dest_options:
          type: object
        destinations:
          example:
          - twitter_x
          - assets
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        last_run_at:
          format: date-time
          nullable: true
          type: string
        last_run_status:
          enum:
          - pending
          - running
          - success
          - failed
          nullable: true
          type: string
        next_run_at:
          format: date-time
          nullable: true
          type: string
        recur_days:
          example:
          - monday
          - thursday
          items:
            type: string
          nullable: true
          type: array
        recur_end_date:
          format: date
          nullable: true
          type: string
        recur_time:
          description: HH:MM UTC
          example: 09:00
          nullable: true
          type: string
        regen_brief:
          nullable: true
          type: string
        regen_continuity:
          type: boolean
        regen_extra_instr:
          nullable: true
          type: string
        run_at:
          description: One-time run datetime (UTC)
          format: date-time
          nullable: true
          type: string
        run_count:
          type: integer
        schedule_type:
          enum:
          - one_time
          - recurring
          type: string
        status:
          enum:
          - active
          - paused
          - cancelled
          - completed
          type: string
      type: object
    CreatorScheduleInput:
      properties:
        content_mode:
          default: current
          enum:
          - current
          - regenerate
          type: string
        dest_options:
          description: 'Per-destination options (e.g. {twitter_x: {summary_200w: true}})'
          type: object
        destinations:
          description: At least one destination is required
          items:
            enum:
            - twitter_x
            - linkedin
            - assets
            - website
            - wiki
            - helpcenter
            - community
            type: string
          type: array
        recur_days:
          description: Required for recurring
          example:
          - monday
          - wednesday
          - friday
          items:
            type: string
          type: array
        recur_end_date:
          description: Optional end date for recurring schedules
          format: date
          type: string
        recur_time:
          description: Required for recurring. "HH:MM" UTC
          example: 09:00
          type: string
        regen_brief:
          description: Brief for AI regeneration (content_mode=regenerate)
          type: string
        regen_continuity:
          default: false
          description: Pass previous run content to AI as context
          type: boolean
        regen_extra_instr:
          description: Extra instructions appended to AI prompt
          type: string
        run_at:
          description: Required for one_time
          format: date-time
          type: string
        schedule_type:
          enum:
          - one_time
          - recurring
          type: string
      required:
      - schedule_type
      - destinations
      type: object
    CreatorScheduleRun:
      properties:
        completed_at:
          format: date-time
          nullable: true
          type: string
        destinations_log:
          description: Per-destination result map
          type: object
        error_msg:
          nullable: true
          type: string
        generated_title:
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        run_at:
          format: date-time
          type: string
        status:
          enum:
          - pending
          - running
          - success
          - failed
          type: string
      type: object
    CrmActivity:
      properties:
        activity_type:
          enum:
          - call
          - email_sent
          - meeting
          - linkedin
          - demo
          - other
          type: string
        body:
          nullable: true
          type: string
        company_id:
          nullable: true
          type: integer
        contact_id:
          nullable: true
          type: integer
        created_at:
          format: date-time
          type: string
        deal_id:
          nullable: true
          type: integer
        duration_mins:
          nullable: true
          type: integer
        id:
          type: integer
        occurred_at:
          format: date-time
          nullable: true
          type: string
        owner_id:
          nullable: true
          type: integer
        subject:
          nullable: true
          type: string
      type: object
    CrmActivityInput:
      properties:
        activity_type:
          default: note
          enum:
          - call
          - email_sent
          - meeting
          - linkedin
          - demo
          - other
          type: string
        body:
          type: string
        company_id:
          type: integer
        contact_id:
          type: integer
        deal_id:
          type: integer
        duration_mins:
          type: integer
        occurred_at:
          format: date-time
          type: string
        owner_id:
          type: integer
        subject:
          type: string
      type: object
    CrmCampaign:
      properties:
        click_rate:
          type: number
        created_at:
          format: date-time
          type: string
        from_email:
          nullable: true
          type: string
        from_name:
          nullable: true
          type: string
        id:
          type: integer
        list_id:
          nullable: true
          type: integer
        name:
          type: string
        open_rate:
          description: Percentage, e.g. 24.5
          type: number
        preview_text:
          nullable: true
          type: string
        reply_to:
          nullable: true
          type: string
        scheduled_at:
          format: date-time
          nullable: true
          type: string
        sent_at:
          format: date-time
          nullable: true
          type: string
        status:
          enum:
          - draft
          - scheduled
          - sending
          - sent
          - cancelled
          type: string
        subject:
          type: string
        total_bounces:
          type: integer
        total_clicks:
          type: integer
        total_opens:
          type: integer
        total_sent:
          type: integer
        total_unsubs:
          type: integer
        updated_at:
          format: date-time
          type: string
      type: object
    CrmCampaignInput:
      properties:
        body_html:
          description: HTML email body
          type: string
        from_email:
          format: email
          type: string
        from_name:
          type: string
        list_id:
          type: integer
        name:
          type: string
        preview_text:
          type: string
        reply_to:
          format: email
          type: string
        subject:
          type: string
      required:
      - name
      - subject
      type: object
    CrmCompany:
      properties:
        address:
          nullable: true
          type: string
        city:
          nullable: true
          type: string
        country:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        domain:
          example: acme.com
          nullable: true
          type: string
        id:
          type: integer
        industry:
          nullable: true
          type: string
        linkedin_url:
          nullable: true
          type: string
        name:
          example: Acme Corp
          type: string
        owner_id:
          nullable: true
          type: integer
        phone:
          nullable: true
          type: string
        size:
          example: 51-200
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
        website:
          nullable: true
          type: string
      type: object
    CrmCompanyInput:
      properties:
        address:
          type: string
        city:
          type: string
        country:
          type: string
        description:
          type: string
        domain:
          type: string
        industry:
          type: string
        linkedin_url:
          type: string
        name:
          type: string
        owner_id:
          type: integer
        phone:
          type: string
        size:
          enum:
          - 1-10
          - 11-50
          - 51-200
          - 201-500
          - 500+
          type: string
        website:
          type: string
      required:
      - name
      type: object
    CrmContact:
      properties:
        city:
          nullable: true
          type: string
        company_name:
          nullable: true
          type: string
        country:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        email:
          nullable: true
          type: string
        first_name:
          nullable: true
          type: string
        full_name:
          example: Jane Smith
          type: string
        id:
          type: integer
        is_unsubscribed:
          type: boolean
        job_title:
          nullable: true
          type: string
        last_name:
          nullable: true
          type: string
        lead_score:
          type: integer
        lead_source:
          nullable: true
          type: string
        lifecycle_stage:
          enum:
          - subscriber
          - lead
          - marketing_qualified_lead
          - sales_qualified_lead
          - opportunity
          - customer
          - evangelist
          type: string
        linkedin_url:
          nullable: true
          type: string
        mobile:
          nullable: true
          type: string
        owner_id:
          nullable: true
          type: integer
        phone:
          nullable: true
          type: string
        tags:
          items:
            $ref: '#/components/schemas/CrmTag'
          type: array
        twitter_handle:
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
        website:
          nullable: true
          type: string
      type: object
    CrmContactInput:
      properties:
        city:
          type: string
        company_name:
          type: string
        country:
          type: string
        description:
          type: string
        email:
          format: email
          type: string
        first_name:
          type: string
        is_unsubscribed:
          type: boolean
        job_title:
          type: string
        last_name:
          type: string
        lead_score:
          default: 0
          type: integer
        lead_source:
          type: string
        lifecycle_stage:
          default: lead
          enum:
          - subscriber
          - lead
          - marketing_qualified_lead
          - sales_qualified_lead
          - opportunity
          - customer
          - evangelist
          type: string
        linkedin_url:
          type: string
        mobile:
          type: string
        owner_id:
          type: integer
        phone:
          type: string
        tag_ids:
          items:
            type: integer
          type: array
        twitter_handle:
          type: string
        website:
          type: string
      type: object
    CrmDeal:
      properties:
        amount:
          example: 12000
          nullable: true
          type: number
        close_date:
          format: date
          nullable: true
          type: string
        closed_at:
          format: date-time
          nullable: true
          type: string
        company_ids:
          items:
            type: integer
          type: array
        contact_ids:
          items:
            type: integer
          type: array
        created_at:
          format: date-time
          type: string
        currency:
          example: USD
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        lost_reason:
          nullable: true
          type: string
        owner_id:
          nullable: true
          type: integer
        pipeline_id:
          nullable: true
          type: integer
        stage_id:
          nullable: true
          type: integer
        status:
          enum:
          - open
          - won
          - lost
          type: string
        title:
          example: Acme Corp - Enterprise Plan
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    CrmDealInput:
      properties:
        amount:
          type: number
        close_date:
          format: date
          type: string
        company_ids:
          items:
            type: integer
          type: array
        contact_ids:
          items:
            type: integer
          type: array
        currency:
          default: USD
          type: string
        description:
          type: string
        lost_reason:
          type: string
        owner_id:
          type: integer
        pipeline_id:
          type: integer
        stage_id:
          type: integer
        status:
          enum:
          - open
          - won
          - lost
          type: string
        title:
          type: string
      required:
      - title
      type: object
    CrmForm:
      properties:
        add_to_list_id:
          nullable: true
          type: integer
        assign_stage:
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        field_count:
          type: integer
        id:
          type: integer
        is_active:
          type: boolean
        name:
          type: string
        public_url:
          type: string
        redirect_url:
          nullable: true
          type: string
        submission_count:
          type: integer
        submit_text:
          default: Submit
          type: string
        title:
          nullable: true
          type: string
        token:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    CrmList:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        filter_criteria:
          nullable: true
          type: object
        id:
          type: integer
        list_type:
          enum:
          - static
          - smart
          type: string
        member_count:
          type: integer
        name:
          example: Newsletter Subscribers
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    CrmListInput:
      properties:
        description:
          type: string
        filter_criteria:
          description: 'Used for smart lists. Keys: lifecycle_stage, lead_source,
            country, etc.'
          type: object
        list_type:
          default: static
          enum:
          - static
          - smart
          type: string
        name:
          type: string
      required:
      - name
      type: object
    CrmNote:
      properties:
        author_id:
          nullable: true
          type: integer
        body:
          type: string
        company_id:
          nullable: true
          type: integer
        contact_id:
          nullable: true
          type: integer
        created_at:
          format: date-time
          type: string
        deal_id:
          nullable: true
          type: integer
        id:
          type: integer
        updated_at:
          format: date-time
          type: string
      type: object
    CrmNoteInput:
      properties:
        body:
          type: string
        company_id:
          type: integer
        contact_id:
          type: integer
        deal_id:
          type: integer
      required:
      - body
      type: object
    CrmPipeline:
      properties:
        created_at:
          format: date-time
          type: string
        currency:
          example: USD
          type: string
        id:
          type: integer
        is_default:
          type: boolean
        name:
          example: Sales Pipeline
          type: string
        stages:
          items:
            $ref: '#/components/schemas/CrmPipelineStage'
          type: array
      type: object
    CrmPipelineInput:
      properties:
        currency:
          default: USD
          type: string
        is_default:
          default: false
          type: boolean
        name:
          type: string
        stages:
          description: Optional. If omitted, 6 default stages are created.
          items:
            properties:
              color:
                type: string
              is_lost:
                type: boolean
              is_won:
                type: boolean
              name:
                type: string
              position:
                type: integer
              probability:
                type: integer
            type: object
          type: array
      required:
      - name
      type: object
    CrmPipelineStage:
      properties:
        color:
          example: '#3b82f6'
          type: string
        id:
          type: integer
        is_lost:
          type: boolean
        is_won:
          type: boolean
        name:
          example: Proposal
          type: string
        pipeline_id:
          type: integer
        position:
          type: integer
        probability:
          description: 0–100
          type: integer
      type: object
    CrmProduct:
      properties:
        created_at:
          format: date-time
          type: string
        currency:
          example: USD
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        is_active:
          type: boolean
        name:
          example: Enterprise Plan
          type: string
        price:
          example: 999
          nullable: true
          type: number
        sku:
          nullable: true
          type: string
      type: object
    CrmProductInput:
      properties:
        currency:
          default: USD
          type: string
        description:
          type: string
        is_active:
          default: true
          type: boolean
        name:
          type: string
        price:
          type: number
        sku:
          type: string
      required:
      - name
      type: object
    CrmTag:
      properties:
        color:
          example: '#6b7280'
          type: string
        id:
          type: integer
        name:
          example: VIP
          type: string
      type: object
    CrmTagInput:
      properties:
        color:
          default: '#6b7280'
          type: string
        name:
          type: string
      required:
      - name
      type: object
    CrmTask:
      properties:
        assigned_to:
          nullable: true
          type: integer
        company_id:
          nullable: true
          type: integer
        completed_at:
          format: date-time
          nullable: true
          type: string
        contact_id:
          nullable: true
          type: integer
        created_at:
          format: date-time
          type: string
        deal_id:
          nullable: true
          type: integer
        description:
          nullable: true
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        id:
          type: integer
        priority:
          enum:
          - low
          - medium
          - high
          - urgent
          type: string
        status:
          enum:
          - open
          - completed
          - cancelled
          type: string
        task_type:
          enum:
          - follow_up
          - call
          - email
          - meeting
          - send_proposal
          - other
          type: string
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    CrmTaskInput:
      properties:
        assigned_to:
          type: integer
        company_id:
          type: integer
        contact_id:
          type: integer
        deal_id:
          type: integer
        description:
          type: string
        due_date:
          format: date
          type: string
        priority:
          default: medium
          enum:
          - low
          - medium
          - high
          - urgent
          type: string
        status:
          default: open
          enum:
          - open
          - completed
          - cancelled
          type: string
        task_type:
          default: follow_up
          enum:
          - follow_up
          - call
          - email
          - meeting
          - send_proposal
          - other
          type: string
        title:
          type: string
      required:
      - title
      type: object
    Error:
      properties:
        error:
          properties:
            code:
              example: not_found
              type: string
            message:
              example: Survey not found.
              type: string
          type: object
      type: object
    Expense:
      properties:
        amount:
          type: number
        category:
          nullable: true
          type: string
        currency:
          type: string
        date:
          format: date
          type: string
        description:
          type: string
        id:
          type: integer
        status:
          enum:
          - draft
          - submitted
          - approved
          - paid
          - rejected
          type: string
      type: object
    FileRequest:
      properties:
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          nullable: true
          type: string
        id:
          type: integer
        is_active:
          type: boolean
        is_expired:
          type: boolean
        is_open:
          type: boolean
        message:
          nullable: true
          type: string
        submission_count:
          type: integer
        title:
          type: string
        token:
          example: d8b3e1a2f5c9...
          type: string
        upload_url:
          example: /ftr/d8b3e1a2f5c9...
          type: string
      type: object
    FileRequestInput:
      properties:
        expires_in:
          default: never
          enum:
          - '1'
          - '3'
          - '7'
          - '30'
          - never
          type: string
        message:
          description: Instructions shown to the uploader.
          type: string
        title:
          example: Please upload your signed contract
          type: string
      required:
      - title
      type: object
    FileRequestSubmission:
      properties:
        files:
          items:
            properties:
              content_type:
                nullable: true
                type: string
              file_size:
                type: integer
              file_size_human:
                type: string
              filename:
                type: string
              id:
                type: integer
            type: object
          type: array
        id:
          type: integer
        message:
          nullable: true
          type: string
        request_id:
          type: integer
        submitted_at:
          format: date-time
          type: string
        total_size:
          type: integer
        total_size_human:
          type: string
        uploader_email:
          nullable: true
          type: string
        uploader_name:
          nullable: true
          type: string
      type: object
    FileTransfer:
      properties:
        created_at:
          format: date-time
          type: string
        download_count:
          type: integer
        download_url:
          example: /ft/a3f7c9e2b1d4...
          type: string
        expires_at:
          format: date-time
          nullable: true
          type: string
        file_count:
          type: integer
        files:
          items:
            properties:
              content_type:
                nullable: true
                type: string
              file_size:
                type: integer
              file_size_human:
                type: string
              filename:
                type: string
              id:
                type: integer
            type: object
          type: array
        id:
          type: integer
        is_accessible:
          type: boolean
        is_active:
          type: boolean
        is_expired:
          type: boolean
        is_password_protected:
          type: boolean
        max_downloads:
          description: null = unlimited
          nullable: true
          type: integer
        message:
          nullable: true
          type: string
        recipients:
          items:
            properties:
              email:
                type: string
              name:
                nullable: true
                type: string
              notified_at:
                format: date-time
                nullable: true
                type: string
            type: object
          type: array
        title:
          nullable: true
          type: string
        token:
          example: a3f7c9e2b1d4...
          type: string
        total_size:
          description: Total size in bytes
          type: integer
        total_size_human:
          example: 4.2 MB
          type: string
      type: object
    FileTransferInput:
      description: Use `multipart/form-data` to send files. All other fields are optional
        form fields alongside the `files[]` part.
      properties:
        expires_in:
          default: '7'
          description: Number of days until the link expires, or "never".
          enum:
          - '1'
          - '3'
          - '7'
          - '14'
          - '30'
          - never
          type: string
        max_downloads:
          description: Maximum number of downloads allowed. Omit for unlimited.
          type: integer
        message:
          example: Here are the files you requested.
          type: string
        password:
          description: Optional password to protect the download link.
          type: string
        recipient_emails:
          description: Newline- or comma-separated email addresses to notify.
          example: 'alice@example.com

            bob@example.com'
          type: string
        title:
          example: Q4 design assets
          type: string
      type: object
    HelpArticle:
      properties:
        author:
          type: string
        body:
          description: HTML content (included in single-article GET only)
          type: string
        category:
          nullable: true
          type: string
        category_id:
          nullable: true
          type: integer
        created_at:
          format: date-time
          type: string
        excerpt:
          nullable: true
          type: string
        helpful_no:
          type: integer
        helpful_yes:
          type: integer
        id:
          type: integer
        is_featured:
          type: boolean
        published_at:
          format: date-time
          nullable: true
          type: string
        slug:
          type: string
        status:
          enum:
          - draft
          - published
          type: string
        title:
          type: string
        updated_at:
          format: date-time
          type: string
        views:
          type: integer
      type: object
    HelpArticleInput:
      properties:
        body:
          description: HTML content
          type: string
        category_id:
          nullable: true
          type: integer
        excerpt:
          type: string
        is_featured:
          default: false
          type: boolean
        meta_description:
          type: string
        status:
          default: draft
          enum:
          - draft
          - published
          type: string
        title:
          type: string
      required:
      - title
      type: object
    HelpCategory:
      properties:
        article_count:
          type: integer
        color:
          example: '#3b82f6'
          type: string
        description:
          nullable: true
          type: string
        icon:
          example: bi-folder
          type: string
        id:
          type: integer
        is_published:
          type: boolean
        order:
          type: integer
        parent_id:
          nullable: true
          type: integer
        slug:
          type: string
        title:
          type: string
      type: object
    Invoice:
      properties:
        balance_due:
          type: number
        contact_id:
          nullable: true
          type: integer
        currency:
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        id:
          type: integer
        invoice_number:
          type: string
        issue_date:
          format: date
          type: string
        status:
          enum:
          - draft
          - sent
          - paid
          - overdue
          - voided
          type: string
        subtotal:
          type: number
        tax_amount:
          type: number
        total:
          type: number
      type: object
    Issue:
      properties:
        assignee:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        body:
          description: Sanitized HTML. Only present in single-issue GET and list with
            detail flag.
          nullable: true
          type: string
        comment_count:
          type: integer
        created_at:
          format: date-time
          type: string
        created_by:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        due_date:
          format: date
          nullable: true
          type: string
        epic_id:
          nullable: true
          type: integer
        estimate:
          description: Story points or hours
          nullable: true
          type: number
        id:
          type: integer
        identifier:
          example: BACK-42
          type: string
        is_archived:
          type: boolean
        issue_type:
          enum:
          - bug
          - story
          - task
          - improvement
          - question
          - feature
          type: string
        labels:
          items:
            $ref: '#/components/schemas/IssueLabel'
          type: array
        milestone_id:
          nullable: true
          type: integer
        number:
          type: integer
        parent_id:
          nullable: true
          type: integer
        priority:
          enum:
          - urgent
          - high
          - medium
          - low
          - none
          type: string
        project_id:
          type: integer
        project_key:
          example: BACK
          type: string
        resolved_at:
          format: date-time
          nullable: true
          type: string
        status:
          $ref: '#/components/schemas/IssueStatus'
          nullable: true
        sub_issues:
          description: Present in detail view only.
          items:
            properties:
              id:
                type: integer
              identifier:
                type: string
              title:
                type: string
            type: object
          type: array
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    IssueActivity:
      properties:
        action:
          example: status_changed
          type: string
        actor:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        issue_id:
          type: integer
        new_value:
          nullable: true
          type: string
        note:
          nullable: true
          type: string
        old_value:
          nullable: true
          type: string
      type: object
    IssueComment:
      properties:
        author:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        body:
          description: Sanitized HTML
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        issue_id:
          type: integer
        updated_at:
          format: date-time
          type: string
      type: object
    IssueCommentInput:
      properties:
        body:
          description: HTML content — sanitized server-side
          type: string
      required:
      - body
      type: object
    IssueCustomField:
      properties:
        field_type:
          enum:
          - short_text
          - long_text
          - dropdown
          - yes_no
          type: string
        id:
          format: uuid
          type: string
        is_enabled:
          type: boolean
        is_required:
          type: boolean
        options:
          items:
            type: string
          type: array
        order:
          type: integer
        project_keys:
          description: Populated when scope=projects
          items:
            type: string
          type: array
        scope:
          description: global = all projects; projects = scoped to specific projects
          enum:
          - global
          - projects
          type: string
        title:
          example: Severity
          type: string
        tooltip:
          nullable: true
          type: string
      type: object
    IssueCustomFieldInput:
      properties:
        field_type:
          enum:
          - short_text
          - long_text
          - dropdown
          - yes_no
          type: string
        is_required:
          default: false
          type: boolean
        options:
          description: Required when field_type=dropdown
          items:
            type: string
          type: array
        project_keys:
          description: Required when scope=projects
          items:
            type: string
          type: array
        scope:
          default: global
          enum:
          - global
          - projects
          type: string
        title:
          example: Severity
          type: string
        tooltip:
          type: string
      required:
      - title
      - field_type
      type: object
    IssueCustomFieldValue:
      properties:
        field_id:
          format: uuid
          type: string
        value:
          description: String value; "yes" for yes_no fields
          type: string
      type: object
    IssueEpic:
      properties:
        color:
          example: '#8b5cf6'
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        issue_count:
          type: integer
        project_id:
          type: integer
        start_date:
          format: date
          nullable: true
          type: string
        status:
          enum:
          - open
          - in_progress
          - completed
          - cancelled
          type: string
        target_date:
          format: date
          nullable: true
          type: string
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    IssueEpicInput:
      properties:
        color:
          default: '#8b5cf6'
          type: string
        description:
          type: string
        start_date:
          format: date
          type: string
        status:
          default: open
          enum:
          - open
          - in_progress
          - completed
          - cancelled
          type: string
        target_date:
          format: date
          type: string
        title:
          type: string
      required:
      - title
      type: object
    IssueInitiative:
      properties:
        color:
          example: '#6366f1'
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        health:
          enum:
          - on_track
          - at_risk
          - off_track
          type: string
        id:
          type: integer
        name:
          type: string
        owner:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        project_count:
          type: integer
        status:
          enum:
          - planned
          - active
          - completed
          - cancelled
          type: string
        target_date:
          format: date
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    IssueInitiativeInput:
      properties:
        color:
          default: '#6366f1'
          type: string
        description:
          type: string
        health:
          default: on_track
          enum:
          - on_track
          - at_risk
          - off_track
          type: string
        name:
          type: string
        owner_id:
          type: integer
        status:
          default: planned
          enum:
          - planned
          - active
          - completed
          - cancelled
          type: string
        target_date:
          format: date
          type: string
      required:
      - name
      type: object
    IssueInput:
      properties:
        assignee_id:
          nullable: true
          type: integer
        body:
          description: HTML content — will be sanitized server-side
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        epic_id:
          nullable: true
          type: integer
        estimate:
          nullable: true
          type: number
        issue_type:
          default: task
          enum:
          - bug
          - story
          - task
          - improvement
          - question
          - feature
          type: string
        milestone_id:
          nullable: true
          type: integer
        parent_id:
          description: Parent issue ID (creates a sub-issue)
          nullable: true
          type: integer
        priority:
          default: none
          enum:
          - urgent
          - high
          - medium
          - low
          - none
          type: string
        status_id:
          description: Defaults to first workflow status
          type: integer
        title:
          example: Login button broken on Safari
          type: string
      required:
      - title
      type: object
    IssueLabel:
      properties:
        color:
          example: '#6b7280'
          type: string
        id:
          type: integer
        name:
          example: frontend
          type: string
        project_id:
          description: null = tenant-wide label
          nullable: true
          type: integer
      type: object
    IssueLabelInput:
      properties:
        color:
          default: '#6b7280'
          type: string
        name:
          type: string
        project_key:
          description: Scope label to a project (omit for tenant-wide)
          type: string
      required:
      - name
      type: object
    IssueMilestone:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        issue_count:
          type: integer
        project_id:
          type: integer
        status:
          enum:
          - open
          - completed
          type: string
        target_date:
          format: date
          nullable: true
          type: string
        title:
          type: string
      type: object
    IssueMilestoneInput:
      properties:
        description:
          type: string
        status:
          default: open
          enum:
          - open
          - completed
          type: string
        target_date:
          format: date
          type: string
        title:
          type: string
      required:
      - title
      type: object
    IssueProject:
      properties:
        color:
          example: '#3b82f6'
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        icon:
          example: bi-kanban
          type: string
        id:
          type: integer
        is_private:
          type: boolean
        issue_count:
          type: integer
        key:
          example: BACKEND
          type: string
        lead:
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
          type: object
        name:
          example: Backend API
          type: string
        status:
          enum:
          - backlog
          - active
          - paused
          - completed
          type: string
        target_date:
          format: date
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
        workflow_id:
          nullable: true
          type: integer
      type: object
    IssueProjectInput:
      properties:
        color:
          example: '#3b82f6'
          type: string
        description:
          type: string
        icon:
          example: bi-kanban
          type: string
        is_private:
          default: false
          type: boolean
        key:
          description: 1–10 alphanumeric characters used as issue prefix (e.g. BACK-42)
          example: BACK
          type: string
        name:
          example: Backend API
          type: string
        status:
          default: active
          enum:
          - backlog
          - active
          - paused
          - completed
          type: string
        target_date:
          format: date
          type: string
      required:
      - name
      - key
      type: object
    IssueSprint:
      properties:
        created_at:
          format: date-time
          type: string
        end_date:
          format: date
          nullable: true
          type: string
        goal:
          nullable: true
          type: string
        id:
          type: integer
        issue_count:
          type: integer
        name:
          example: Sprint 12
          type: string
        number:
          type: integer
        project_id:
          type: integer
        start_date:
          format: date
          nullable: true
          type: string
        status:
          enum:
          - planned
          - active
          - completed
          type: string
      type: object
    IssueSprintInput:
      properties:
        end_date:
          format: date
          type: string
        goal:
          type: string
        name:
          type: string
        start_date:
          format: date
          type: string
        status:
          default: planned
          enum:
          - planned
          - active
          - completed
          type: string
      required:
      - name
      type: object
    IssueStatus:
      properties:
        category:
          enum:
          - backlog
          - unstarted
          - started
          - completed
          - cancelled
          - triage
          type: string
        color:
          example: '#3b82f6'
          type: string
        id:
          type: integer
        is_terminal:
          type: boolean
        name:
          example: In Progress
          type: string
        position:
          type: integer
        workflow_id:
          type: integer
      type: object
    IssueStatusTransitionInput:
      properties:
        status_id:
          description: ID of the target status
          type: integer
      required:
      - status_id
      type: object
    IssueUpdateInput:
      properties:
        assignee_id:
          nullable: true
          type: integer
        body:
          description: HTML — sanitized server-side
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        epic_id:
          nullable: true
          type: integer
        estimate:
          nullable: true
          type: number
        is_archived:
          type: boolean
        issue_type:
          enum:
          - bug
          - story
          - task
          - improvement
          - question
          - feature
          type: string
        milestone_id:
          nullable: true
          type: integer
        parent_id:
          nullable: true
          type: integer
        priority:
          enum:
          - urgent
          - high
          - medium
          - low
          - none
          type: string
        status_id:
          nullable: true
          type: integer
        title:
          type: string
      type: object
    Meta:
      properties:
        has_next:
          type: boolean
        has_prev:
          type: boolean
        page:
          example: 1
          type: integer
        pages:
          example: 3
          type: integer
        per_page:
          example: 20
          type: integer
        total:
          example: 42
          type: integer
      type: object
    Newsletter:
      properties:
        created_at:
          format: date-time
          type: string
        double_optin:
          type: boolean
        from_email:
          format: email
          type: string
        from_name:
          type: string
        is_active:
          type: boolean
        issue_count:
          type: integer
        name:
          type: string
        reply_to:
          format: email
          nullable: true
          type: string
        slug:
          type: string
        subscriber_count:
          type: integer
        uuid:
          format: uuid
          type: string
      type: object
    NewsletterAnalytics:
      properties:
        active_subscribers:
          type: integer
        avg_click_rate:
          description: Average click rate across all sent issues, 0–100
          format: float
          type: number
        avg_open_rate:
          description: Average open rate across all sent issues, 0–100
          format: float
          type: number
        issues_sent:
          type: integer
        newsletter_name:
          type: string
        newsletter_uuid:
          format: uuid
          type: string
        total_clicks:
          type: integer
        total_opens:
          type: integer
        total_sends:
          type: integer
        total_subscribers:
          type: integer
      type: object
    NewsletterEdition:
      properties:
        click_count:
          type: integer
        click_rate:
          description: Unique click rate 0–100
          format: float
          type: number
        content_html:
          description: Full HTML body (only in single-issue endpoint)
          type: string
        created_at:
          format: date-time
          type: string
        open_count:
          type: integer
        open_rate:
          description: Unique open rate 0–100
          format: float
          type: number
        preview_text:
          nullable: true
          type: string
        recipient_count:
          type: integer
        scheduled_at:
          format: date-time
          nullable: true
          type: string
        sent_at:
          format: date-time
          nullable: true
          type: string
        status:
          enum:
          - draft
          - scheduled
          - sending
          - sent
          - cancelled
          type: string
        subject:
          type: string
        uuid:
          format: uuid
          type: string
        web_published:
          type: boolean
      type: object
    NewsletterSubscriber:
      properties:
        created_at:
          format: date-time
          type: string
        email:
          format: email
          type: string
        first_name:
          nullable: true
          type: string
        last_name:
          nullable: true
          type: string
        status:
          enum:
          - pending
          - active
          - unsubscribed
          - bounced
          - complained
          type: string
        subscribed_at:
          format: date-time
          nullable: true
          type: string
        uuid:
          format: uuid
          type: string
      type: object
    NewsletterSubscriberInput:
      properties:
        email:
          format: email
          type: string
        first_name:
          type: string
        last_name:
          type: string
      required:
      - email
      type: object
    Note:
      properties:
        color:
          example: '#fef9c3'
          type: string
        content:
          description: Quill Delta JSON string. Only included when fetching a single
            note.
          type: string
        created_at:
          format: date-time
          type: string
        excerpt:
          description: Plain-text preview (≤500 chars).
          type: string
        id:
          type: integer
        is_pinned:
          type: boolean
        is_trashed:
          type: boolean
        notebook_id:
          type: integer
        tags:
          items:
            $ref: '#/components/schemas/NoteTag'
          type: array
        title:
          example: Meeting agenda
          type: string
        trashed_at:
          format: date-time
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    NoteInput:
      properties:
        color:
          example: '#fef9c3'
          type: string
        content:
          description: Quill Delta JSON string or object.
          example: '{"ops":[{"insert":"Hello world\n"}]}'
          type: string
        is_pinned:
          type: boolean
        notebook_id:
          description: Defaults to the default notebook.
          nullable: true
          type: integer
        tag_ids:
          items:
            type: integer
          type: array
        title:
          example: Meeting agenda
          type: string
      type: object
    NoteShare:
      properties:
        id:
          type: integer
        note_id:
          type: integer
        permission:
          enum:
          - view
          - edit
          type: string
        user_id:
          type: integer
        user_name:
          nullable: true
          type: string
      type: object
    NoteShareInput:
      properties:
        permission:
          default: view
          enum:
          - view
          - edit
          type: string
        user_id:
          type: integer
      required:
      - user_id
      type: object
    NoteTag:
      properties:
        color:
          example: '#3b82f6'
          type: string
        id:
          type: integer
        name:
          example: work
          type: string
      type: object
    NoteTagInput:
      properties:
        color:
          example: '#3b82f6'
          type: string
        name:
          example: work
          type: string
      required:
      - name
      type: object
    Notebook:
      properties:
        color:
          example: '#3b82f6'
          type: string
        icon:
          example: bi-journal
          type: string
        id:
          type: integer
        is_default:
          type: boolean
        note_count:
          type: integer
        order:
          type: integer
        title:
          example: Personal
          type: string
      type: object
    NotebookInput:
      properties:
        color:
          example: '#3b82f6'
          type: string
        icon:
          example: bi-journal
          type: string
        title:
          example: Personal
          type: string
      required:
      - title
      type: object
    PrRequest:
      properties:
        affected_users:
          nullable: true
          type: string
        attachments:
          items:
            properties:
              created_at:
                format: date-time
                nullable: true
                type: string
              field_id:
                nullable: true
                type: integer
              filename:
                type: string
              mime_type:
                nullable: true
                type: string
              size:
                nullable: true
                type: integer
              uid:
                type: string
            type: object
          type: array
        comment_count:
          type: integer
        created_at:
          format: date-time
          nullable: true
          type: string
        current_workaround:
          nullable: true
          type: string
        custom_fields:
          additionalProperties:
            properties:
              label:
                type: string
              type:
                type: string
              value: {}
            type: object
          description: Board custom-field values, keyed by api_key. Multi-select values
            are arrays.
          type: object
        downvote_count:
          type: integer
        frequency:
          nullable: true
          type: string
        impact_description:
          nullable: true
          type: string
        is_public:
          type: boolean
        problem_statement:
          description: Full (single-request) view only
          nullable: true
          type: string
        product_eta:
          nullable: true
          type: string
        product_response:
          nullable: true
          type: string
        severity:
          enum:
          - blocker
          - significant
          - minor
          type: string
        status:
          type: string
        submitter_email:
          nullable: true
          type: string
        submitter_name:
          nullable: true
          type: string
        suggested_solution:
          nullable: true
          type: string
        tags:
          items:
            type: string
          type: array
        title:
          type: string
        uid:
          type: string
        updated_at:
          format: date-time
          nullable: true
          type: string
        upvote_count:
          type: integer
      type: object
    PrRequestInput:
      properties:
        affected_users:
          type: string
        crm_contact_id:
          type: integer
        csm_account_id:
          type: integer
        current_workaround:
          type: string
        custom_fields:
          additionalProperties: true
          description: '{api_key: value} for board custom fields. Lists allowed for
            multi-select. Attachment fields are upload-only.'
          type: object
        frequency:
          enum:
          - daily
          - weekly
          - monthly
          - rarely
          type: string
        impact_description:
          type: string
        problem_statement:
          type: string
        severity:
          default: minor
          enum:
          - blocker
          - significant
          - minor
          type: string
        submitter_email:
          format: email
          type: string
        submitter_name:
          type: string
        suggested_solution:
          type: string
        title:
          type: string
      required:
      - title
      - problem_statement
      type: object
    ProfitLoss:
      properties:
        from_date:
          format: date
          type: string
        net_profit:
          type: number
        to_date:
          format: date
          type: string
        total_expenses:
          type: number
        total_revenue:
          type: number
      type: object
    Project:
      properties:
        color:
          example: '#3b82f6'
          type: string
        columns:
          description: Included when fetching a single project.
          items:
            $ref: '#/components/schemas/ProjectColumn'
          type: array
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        icon:
          example: bi-kanban
          type: string
        id:
          type: integer
        is_archived:
          type: boolean
        member_count:
          type: integer
        task_count:
          type: integer
        title:
          example: Q3 Product Launch
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    ProjectColumn:
      properties:
        color:
          example: '#3b82f6'
          type: string
        id:
          type: integer
        is_done:
          type: boolean
        order:
          type: integer
        project_id:
          type: integer
        task_count:
          type: integer
        tasks:
          description: Only included when ?include_tasks=true.
          items:
            $ref: '#/components/schemas/Task'
          type: array
        title:
          example: In Progress
          type: string
      type: object
    ProjectColumnInput:
      properties:
        color:
          example: '#f59e0b'
          type: string
        is_done:
          default: false
          type: boolean
        order:
          type: integer
        title:
          example: Review
          type: string
      required:
      - title
      type: object
    ProjectCustomField:
      properties:
        field_type:
          enum:
          - short_text
          - long_text
          - dropdown
          - yes_no
          type: string
        id:
          format: uuid
          type: string
        is_enabled:
          type: boolean
        is_required:
          type: boolean
        options:
          items:
            type: string
          type: array
        order:
          type: integer
        title:
          example: Customer Name
          type: string
        tooltip:
          nullable: true
          type: string
      type: object
    ProjectCustomFieldInput:
      properties:
        field_type:
          enum:
          - short_text
          - long_text
          - dropdown
          - yes_no
          type: string
        is_required:
          default: false
          type: boolean
        options:
          description: Required when field_type=dropdown
          items:
            type: string
          type: array
        title:
          example: Customer Name
          type: string
        tooltip:
          type: string
      required:
      - title
      - field_type
      type: object
    ProjectInput:
      properties:
        color:
          example: '#3b82f6'
          type: string
        description:
          type: string
        icon:
          example: bi-kanban
          type: string
        is_archived:
          default: false
          type: boolean
        title:
          example: Q3 Product Launch
          type: string
      required:
      - title
      type: object
    Question:
      properties:
        description:
          nullable: true
          type: string
        id:
          type: integer
        options:
          items:
            properties:
              id:
                type: integer
              order:
                type: integer
              text:
                type: string
            type: object
          type: array
        order:
          type: integer
        question_type:
          enum:
          - single_choice
          - multiple_choice
          - text_short
          - text_long
          - rating
          - nps
          - yes_no
          - dropdown
          type: string
        required:
          type: boolean
        scale_max:
          example: 5
          type: integer
        survey_id:
          type: integer
        title:
          type: string
      type: object
    QuestionInput:
      properties:
        description:
          type: string
        options:
          items:
            properties:
              text:
                type: string
            type: object
          type: array
        question_type:
          default: single_choice
          enum:
          - single_choice
          - multiple_choice
          - text_short
          - text_long
          - rating
          - nps
          - yes_no
          - dropdown
          type: string
        required:
          default: true
          type: boolean
        scale_max:
          default: 5
          type: integer
        title:
          example: How satisfied are you?
          type: string
      required:
      - title
      type: object
    Response:
      properties:
        answers:
          items:
            properties:
              answer:
                type: string
              question_id:
                type: integer
            type: object
          type: array
        id:
          type: integer
        respondent_email:
          nullable: true
          type: string
        respondent_name:
          nullable: true
          type: string
        submitted_at:
          format: date-time
          type: string
        survey_id:
          type: integer
      type: object
    StringEntry:
      properties:
        char_count:
          type: integer
        context_notes:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        key:
          example: onboarding.welcome.title
          type: string
        normalized_value:
          type: string
        placeholder_type:
          enum:
          - none
          - icu
          - ios
          - android
          - gettext
          - i18next
          - python
          type: string
        placeholders:
          type: array
        raw_value:
          type: string
        source_file:
          nullable: true
          type: string
        uid:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        word_count:
          type: integer
        word_count_method:
          enum:
          - words
          - characters
          type: string
      type: object
    StringSet:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        entry_count:
          type: integer
        language_count:
          type: integer
        name:
          type: string
        primary_language:
          example: en-US
          nullable: true
          type: string
        uid:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    StringTranslation:
      properties:
        is_reviewed:
          type: boolean
        locale_code:
          example: fr-FR
          type: string
        normalized_value:
          type: string
        raw_value:
          type: string
        uid:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        word_count:
          type: integer
      type: object
    Subtask:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_done:
          type: boolean
        order:
          type: integer
        task_id:
          type: integer
        title:
          example: Draft copy
          type: string
      type: object
    SubtaskInput:
      properties:
        is_done:
          default: false
          type: boolean
        order:
          type: integer
        title:
          example: Draft copy
          type: string
      required:
      - title
      type: object
    Survey:
      properties:
        collect_email:
          type: boolean
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        public_url:
          example: /s/a3f7c...
          type: string
        question_count:
          type: integer
        response_count:
          type: integer
        show_progress_bar:
          type: boolean
        status:
          enum:
          - draft
          - active
          - closed
          type: string
        thank_you_message:
          type: string
        title:
          example: Customer Satisfaction Q2
          type: string
        token:
          example: a3f7c...
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    SurveyInput:
      properties:
        collect_email:
          default: false
          type: boolean
        description:
          type: string
        one_response_per_email:
          default: false
          type: boolean
        show_progress_bar:
          default: true
          type: boolean
        thank_you_message:
          type: string
        title:
          example: Customer Satisfaction Q2
          type: string
      required:
      - title
      type: object
    Task:
      properties:
        assignee_id:
          nullable: true
          type: integer
        assignee_name:
          nullable: true
          type: string
        column_id:
          nullable: true
          type: integer
        comments:
          description: Included when fetching a single task.
          items:
            $ref: '#/components/schemas/TaskComment'
          type: array
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        due_date:
          format: date
          nullable: true
          type: string
        id:
          type: integer
        is_overdue:
          type: boolean
        labels:
          items:
            $ref: '#/components/schemas/TaskLabel'
          type: array
        order:
          type: integer
        priority:
          enum:
          - low
          - medium
          - high
          - critical
          type: string
        project_id:
          type: integer
        subtask_count:
          type: integer
        subtask_done_count:
          type: integer
        subtasks:
          description: Included when fetching a single task.
          items:
            $ref: '#/components/schemas/Subtask'
          type: array
        title:
          example: Write release notes
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    TaskAttachment:
      properties:
        created_at:
          format: date-time
          type: string
        file_size:
          description: Bytes
          type: integer
        id:
          format: uuid
          type: string
        mime_type:
          example: application/pdf
          type: string
        original_filename:
          example: spec.pdf
          type: string
        uploaded_by:
          nullable: true
          type: string
      type: object
    TaskComment:
      properties:
        author_name:
          nullable: true
          type: string
        body:
          example: Looks good, merging tomorrow.
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        task_id:
          type: integer
        updated_at:
          format: date-time
          type: string
        user_id:
          nullable: true
          type: integer
      type: object
    TaskCommentInput:
      properties:
        body:
          example: Looks good, merging tomorrow.
          type: string
      required:
      - body
      type: object
    TaskInput:
      properties:
        assignee_id:
          nullable: true
          type: integer
        column_id:
          nullable: true
          type: integer
        description:
          type: string
        due_date:
          example: '2026-06-30'
          format: date
          type: string
        label_ids:
          items:
            type: integer
          type: array
        priority:
          default: medium
          enum:
          - low
          - medium
          - high
          - critical
          type: string
        title:
          example: Write release notes
          type: string
      required:
      - title
      type: object
    TaskLabel:
      properties:
        color:
          example: '#ef4444'
          type: string
        id:
          type: integer
        project_id:
          type: integer
        title:
          example: Bug
          type: string
      type: object
    TaskLabelInput:
      properties:
        color:
          example: '#ef4444'
          type: string
        title:
          example: Bug
          type: string
      required:
      - title
      type: object
    TenantLanguage:
      properties:
        flag_emoji:
          example: 🇫🇷
          type: string
        id:
          type: integer
        locale_code:
          example: fr-FR
          type: string
        name:
          example: French
          type: string
        native_name:
          example: Français
          type: string
      type: object
    TransferDownloadLog:
      properties:
        downloaded_at:
          format: date-time
          type: string
        file_id:
          nullable: true
          type: integer
        filename:
          description: null for ZIP downloads
          nullable: true
          type: string
        id:
          type: integer
        ip_address:
          nullable: true
          type: string
        is_zip:
          type: boolean
        transfer_id:
          type: integer
      type: object
    UnifiedContact:
      properties:
        company:
          nullable: true
          type: string
        contact_id:
          description: CRM contact ID
          type: integer
        created_at:
          format: date-time
          nullable: true
          type: string
        email:
          format: email
          nullable: true
          type: string
        lifecycle_stage:
          nullable: true
          type: string
        name:
          type: string
        phone:
          nullable: true
          type: string
        sources:
          description: Source apps this contact exists in
          items:
            properties:
              app:
                enum:
                - crm
                - accounting
                - community
                type: string
              id:
                type: integer
            type: object
          type: array
      type: object
    UnifiedContactInput:
      properties:
        company:
          type: string
        custom_fields:
          additionalProperties:
            type: string
          description: Key/value pairs for custom contact fields
          type: object
        email:
          format: email
          type: string
        name:
          example: Jane Smith
          type: string
        phone:
          type: string
      required:
      - name
      type: object
    WebsitePage:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_home:
          type: boolean
        is_published:
          type: boolean
        slug:
          type: string
        title:
          type: string
        updated_at:
          format: date-time
          type: string
        website_id:
          type: integer
      type: object
    WebsiteSite:
      properties:
        created_at:
          format: date-time
          type: string
        custom_domain:
          nullable: true
          type: string
        id:
          type: integer
        is_published:
          type: boolean
        name:
          type: string
        page_count:
          type: integer
        subdomain:
          nullable: true
          type: string
      type: object
    Wiki:
      properties:
        ai_enabled:
          type: boolean
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        id:
          type: integer
        page_count:
          type: integer
        space_count:
          type: integer
        title:
          example: Engineering Wiki
          type: string
        updated_at:
          format: date-time
          type: string
        uuid:
          example: a1b2c3d4-e5f6-...
          format: uuid
          type: string
        verification_expiry_days:
          example: 90
          type: integer
      type: object
    WikiComment:
      properties:
        author_id:
          type: integer
        body:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_resolved:
          type: boolean
        page_id:
          type: integer
        parent_id:
          nullable: true
          type: integer
        updated_at:
          format: date-time
          type: string
        uuid:
          format: uuid
          type: string
      type: object
    WikiPage:
      properties:
        author_id:
          type: integer
        content:
          description: TipTap JSON document (only included when fetching a single
            page)
          nullable: true
          type: object
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        is_verified:
          type: boolean
        parent_id:
          nullable: true
          type: integer
        position:
          type: integer
        slug:
          type: string
        space_id:
          type: integer
        status:
          enum:
          - draft
          - published
          - archived
          type: string
        title:
          example: Getting Started
          type: string
        updated_at:
          format: date-time
          type: string
        uuid:
          format: uuid
          type: string
        verified_at:
          format: date-time
          nullable: true
          type: string
        view_count:
          type: integer
      type: object
    WikiPageInput:
      properties:
        content:
          description: TipTap JSON document
          example:
            content:
            - content:
              - text: Hello world
                type: text
              type: paragraph
            type: doc
          type: object
        parent_id:
          description: Parent page ID for nesting
          nullable: true
          type: integer
        position:
          description: Sort order among siblings
          type: integer
        status:
          default: published
          enum:
          - draft
          - published
          - archived
          type: string
        title:
          example: Getting Started
          type: string
      type: object
    WikiPageVersion:
      properties:
        author_id:
          type: integer
        change_summary:
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        page_id:
          type: integer
        title:
          type: string
        version_number:
          type: integer
      type: object
    WikiSearchResult:
      properties:
        pages:
          items:
            properties:
              excerpt:
                type: string
              space_name:
                type: string
              title:
                type: string
              updated_at:
                format: date-time
                type: string
              url:
                type: string
              uuid:
                format: uuid
                type: string
            type: object
          type: array
        query:
          type: string
        total:
          type: integer
      type: object
    WikiSpace:
      properties:
        color:
          example: '#6366f1'
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        icon:
          example: ⚙️
          nullable: true
          type: string
        id:
          type: integer
        is_private:
          type: boolean
        name:
          example: Engineering
          type: string
        page_count:
          type: integer
        slug:
          example: engineering
          type: string
        uuid:
          format: uuid
          type: string
        wiki_id:
          type: integer
      type: object
    WikiTemplate:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        icon:
          nullable: true
          type: string
        id:
          type: integer
        is_builtin:
          type: boolean
        name:
          example: Meeting Notes
          type: string
        space_id:
          nullable: true
          type: integer
        uuid:
          format: uuid
          type: string
      type: object
  securitySchemes:
    ApiSecretHeader:
      description: Your userSecret
      in: header
      name: X-Api-Secret
      type: apiKey
    ApiTokenHeader:
      description: Your userToken (e.g. `tc_abc123…`)
      in: header
      name: X-Api-Token
      type: apiKey
info:
  contact:
    name: TotalCtrl Support
  description: '## Authentication


    Every request must include your API credentials as headers:


    ```

    X-Api-Token: tc_your_token

    X-Api-Secret: your_secret

    ```


    Alternatively, use `Authorization: Bearer tc_your_token:your_secret`.


    Generate credentials in your account dashboard under **Developer → API Tokens**.


    ## Tenant Scoping


    All data is automatically scoped to the account that issued the token. There is
    no account ID in the URL.


    ## Pagination


    List endpoints support `?page=1&per_page=20` query params (max 100 per page).
    Responses include a `meta` object with `total`, `pages`, `has_next`, `has_prev`.'
  license:
    name: Proprietary
  title: TotalCtrl API
  version: 1.0.0
openapi: 3.0.3
paths:
  /academy/courses:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  courses:
                  - created_at: '2026-06-15T09:00:00+00:00'
                    currency: USD
                    enrollment_count: 42
                    is_free: true
                    lesson_count: 8
                    price: null
                    published_at: '2026-07-01T12:00:00+00:00'
                    slug: getting-started
                    status: published
                    summary: Onboarding basics for new customers.
                    title: Getting Started
                    uid: c0a1b2c3-d4e5-6789-abcd-ef0123456789
                    visibility: members
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      courses:
                        items:
                          properties:
                            created_at:
                              type: string
                            currency:
                              type: string
                            enrollment_count:
                              type: integer
                            is_free:
                              type: boolean
                            lesson_count:
                              type: integer
                            price:
                              nullable: true
                            published_at:
                              type: string
                            slug:
                              type: string
                            status:
                              type: string
                            summary:
                              type: string
                            title:
                              type: string
                            uid:
                              type: string
                            visibility:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List Academy courses. Use ?status=published to filter.
      tags:
      - Academy
  /academy/courses/{course_uid}:
    get:
      parameters:
      - in: path
        name: course_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-06-15T09:00:00+00:00'
                  currency: USD
                  description: A short onboarding course.
                  enrollment_count: 42
                  is_free: true
                  lesson_count: 8
                  modules:
                  - id: 1
                    intro_html: null
                    lessons:
                    - content_type: html
                      duration_min: 5
                      order: 0
                      scorm_version: null
                      title: Welcome
                      uid: l1a2b3c4-d5e6-7890-abcd-ef0123456789
                    order: 0
                    title: Introduction
                  price: null
                  published_at: '2026-07-01T12:00:00+00:00'
                  slug: getting-started
                  status: published
                  summary: Onboarding basics for new customers.
                  title: Getting Started
                  uid: c0a1b2c3-d4e5-6789-abcd-ef0123456789
                  visibility: members
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      currency:
                        type: string
                      description:
                        type: string
                      enrollment_count:
                        type: integer
                      is_free:
                        type: boolean
                      lesson_count:
                        type: integer
                      modules:
                        items:
                          properties:
                            id:
                              type: integer
                            intro_html:
                              nullable: true
                            lessons:
                              items:
                                properties:
                                  content_type:
                                    type: string
                                  duration_min:
                                    type: integer
                                  order:
                                    type: integer
                                  scorm_version:
                                    nullable: true
                                  title:
                                    type: string
                                  uid:
                                    type: string
                                type: object
                              type: array
                            order:
                              type: integer
                            title:
                              type: string
                          type: object
                        type: array
                      price:
                        nullable: true
                      published_at:
                        type: string
                      slug:
                        type: string
                      status:
                        type: string
                      summary:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      visibility:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a course including its modules and lessons.
      tags:
      - Academy
  /academy/courses/{course_uid}/enroll:
    post:
      description: 'Body (JSON): { "email": "learner@example.com" }'
      parameters:
      - in: path
        name: course_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: learner@example.com
            schema:
              properties:
                email:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created: true
                  enrollment_uid: e1f2a3b4-c5d6-7890-abcd-ef0123456789
                  status: active
              schema:
                properties:
                  data:
                    properties:
                      created:
                        type: boolean
                      enrollment_uid:
                        type: string
                      status:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Enroll an existing workspace user (by email) in a course.
      tags:
      - Academy
  /academy/courses/{course_uid}/enrollments:
    get:
      parameters:
      - in: path
        name: course_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  enrollments:
                  - completed_at: null
                    enrolled_at: '2026-07-10T09:00:00+00:00'
                    learner_email: learner@example.com
                    learner_name: Ada Lovelace
                    progress_pct: 40
                    status: active
                    uid: e1f2a3b4-c5d6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      enrollments:
                        items:
                          properties:
                            completed_at:
                              nullable: true
                            enrolled_at:
                              type: string
                            learner_email:
                              type: string
                            learner_name:
                              type: string
                            progress_pct:
                              type: integer
                            status:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List enrollments for a course.
      tags:
      - Academy
  /academy/studio/jobs/{job_uid}:
    get:
      parameters:
      - in: path
        name: job_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_units_estimate: 320
                  ai_units_used: 298
                  completed_at: '2026-07-14T09:12:00+00:00'
                  course_title: Getting Started
                  course_uid: c0a1b2c3-d4e5-6789-abcd-ef0123456789
                  created_at: '2026-07-14T09:05:00+00:00'
                  error: null
                  progress_message: Completed
                  result_course_id: 55
                  stage: assemble
                  status: done
                  uid: j1a2b3c4-d5e6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      ai_units_estimate:
                        type: integer
                      ai_units_used:
                        type: integer
                      completed_at:
                        type: string
                      course_title:
                        type: string
                      course_uid:
                        type: string
                      created_at:
                        type: string
                      error:
                        nullable: true
                      progress_message:
                        type: string
                      result_course_id:
                        type: integer
                      stage:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a Course Studio generation job's status (and its course when done).
      tags:
      - Academy
  /academy/studio/projects:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  projects:
                  - created_at: '2026-07-14T09:00:00+00:00'
                    name: Product 101
                    options:
                      audience: customers
                      grounding: strict
                      include_quizzes: true
                      target_lessons: 12
                      target_modules: 4
                      tone: friendly
                    result_course_id: null
                    uid: p1a2b3c4-d5e6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      projects:
                        items:
                          properties:
                            created_at:
                              type: string
                            name:
                              type: string
                            options:
                              properties:
                                audience:
                                  type: string
                                grounding:
                                  type: string
                                include_quizzes:
                                  type: boolean
                                target_lessons:
                                  type: integer
                                target_modules:
                                  type: integer
                                tone:
                                  type: string
                              type: object
                            result_course_id:
                              nullable: true
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List Course Studio projects (AI course generation from knowledge sources).
      tags:
      - Academy
  /academy/studio/projects/{project_uid}/generate:
    post:
      description: 'Runs in the background and consumes AI Units. Poll GET

        /academy/studio/jobs/<job_uid> for status. The project must already have at

        least one indexed source and be under the per-run AI-Units cap.'
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              example:
                data:
                  ai_units_estimate: 320
                  job_uid: j1a2b3c4-d5e6-7890-abcd-ef0123456789
                  status: pending
              schema:
                properties:
                  data:
                    properties:
                      ai_units_estimate:
                        type: integer
                      job_uid:
                        type: string
                      status:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Start AI generation of a DRAFT course from a project's knowledge sources.
      tags:
      - Academy
  /account:
    get:
      description: Returns basic information about the tenant account associated with
        this API token.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get account info
      tags:
      - Account
  /account/strings/{account_uuid}/api/v1/string-sets/:
    get:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  sets:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    description: iOS + Android UI strings
                    entry_count: 128
                    language_count: 4
                    name: Mobile App
                    primary_language: en
                    uid: 7b1c9e2a-0d44-4e8f-9a1b-2c3d4e5f6a7b
                    updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      sets:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            entry_count:
                              type: integer
                            language_count:
                              type: integer
                            name:
                              type: string
                            primary_language:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: List all active string sets for the tenant.
      tags:
      - String Manager
    post:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: iOS + Android UI strings
              name: Mobile App
              primary_language: en
            schema:
              properties:
                description:
                  type: string
                name:
                  type: string
                primary_language:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  set:
                    created_at: '2026-07-17T12:00:00+00:00'
                    description: iOS + Android UI strings
                    entry_count: 128
                    language_count: 4
                    name: Mobile App
                    primary_language: en
                    uid: 7b1c9e2a-0d44-4e8f-9a1b-2c3d4e5f6a7b
                    updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      set:
                        properties:
                          created_at:
                            type: string
                          description:
                            type: string
                          entry_count:
                            type: integer
                          language_count:
                            type: integer
                          name:
                            type: string
                          primary_language:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Create a new string set.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/:
    delete:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  status: deleted
              schema:
                properties:
                  data:
                    properties:
                      status:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Soft-delete a string set.
      tags:
      - String Manager
    get:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  set:
                    created_at: '2026-07-17T12:00:00+00:00'
                    description: iOS + Android UI strings
                    entry_count: 128
                    language_count: 4
                    languages:
                    - is_rtl: false
                      locale_code: fr-FR
                      sort_order: 0
                    - is_rtl: true
                      locale_code: ar
                      sort_order: 1
                    name: Mobile App
                    primary_language: en
                    uid: 7b1c9e2a-0d44-4e8f-9a1b-2c3d4e5f6a7b
                    updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      set:
                        properties:
                          created_at:
                            type: string
                          description:
                            type: string
                          entry_count:
                            type: integer
                          language_count:
                            type: integer
                          languages:
                            items:
                              properties:
                                is_rtl:
                                  type: boolean
                                locale_code:
                                  type: string
                                sort_order:
                                  type: integer
                              type: object
                            type: array
                          name:
                            type: string
                          primary_language:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Return string set detail with language list.
      tags:
      - String Manager
    patch:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: Updated description
              name: Mobile App v2
              primary_language: en
            schema:
              properties:
                description:
                  type: string
                name:
                  type: string
                primary_language:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  set:
                    created_at: '2026-07-17T12:00:00+00:00'
                    description: iOS + Android UI strings
                    entry_count: 128
                    language_count: 4
                    languages:
                    - is_rtl: false
                      locale_code: fr-FR
                      sort_order: 0
                    - is_rtl: true
                      locale_code: ar
                      sort_order: 1
                    name: Mobile App
                    primary_language: en
                    uid: 7b1c9e2a-0d44-4e8f-9a1b-2c3d4e5f6a7b
                    updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      set:
                        properties:
                          created_at:
                            type: string
                          description:
                            type: string
                          entry_count:
                            type: integer
                          language_count:
                            type: integer
                          languages:
                            items:
                              properties:
                                is_rtl:
                                  type: boolean
                                locale_code:
                                  type: string
                                sort_order:
                                  type: integer
                              type: object
                            type: array
                          name:
                            type: string
                          primary_language:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Update name, description, or primary_language.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/analysis/:
    get:
      description: Returns a summary by severity and the full result list.
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  results:
                  - analysis_type: placeholder_mismatch
                    created_at: '2026-07-17T12:10:00+00:00'
                    locale_code: fr-FR
                    result:
                      message: Translation is missing placeholder {name}.
                    severity: warning
                    string_uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    uid: f0e1d2c3-b4a5-4968-8778-6a5b4c3d2e1f
                  summary:
                    error: 0
                    info: 1
                    warning: 2
              schema:
                properties:
                  data:
                    properties:
                      results:
                        items:
                          properties:
                            analysis_type:
                              type: string
                            created_at:
                              type: string
                            locale_code:
                              type: string
                            result:
                              properties:
                                message:
                                  type: string
                              type: object
                            severity:
                              type: string
                            string_uid:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      summary:
                        properties:
                          error:
                            type: integer
                          info:
                            type: integer
                          warning:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Return current (non-dismissed) analysis results for the set.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/analysis/run:
    post:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  count: 3
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Trigger an analysis run for the set.  Returns the count of new findings.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/analysis/run-ai:
    post:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  count: 5
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Trigger an AI-assisted analysis run for the set.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/download:
    get:
      description: "Query params:\n    format      (required) – one of DOWNLOADABLE_FORMATS\
        \ keys\n    locale_code – BCP-47 code; if provided, translations for this\
        \ locale\n                  are included in the export."
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Export all strings as a file attachment.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/:
    get:
      description: "Query params:\n    q               – full-text search in key /\
        \ raw_value\n    source_file     – filter by exact source_file\n    placeholder_type\
        \ – filter by placeholder_type\n    locale          – 'missing' or a BCP-47\
        \ locale code\n                      'missing' → strings that have no translation\
        \ for any\n                      configured language; locale code → strings\
        \ missing that\n                      specific locale.\n    limit        \
        \   – page size (default 50, max 200)\n    after           – cursor (uid of\
        \ last item from previous page)"
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  next_cursor: null
                  strings:
                  - char_count: 16
                    context_notes: Shown on the home screen
                    created_at: '2026-07-17T12:00:00+00:00'
                    filter_template_uid: null
                    is_plural: false
                    key: home.welcome_title
                    normalized_value: Welcome, {0}!
                    placeholder_type: icu
                    placeholders:
                    - '{name}'
                    plural_rules: null
                    raw_value: Welcome, {name}!
                    source_file: home.json
                    source_format: json
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    updated_at: '2026-07-17T12:00:00+00:00'
                    word_count: 2
                    word_count_method: icu
                  total_count: 128
              schema:
                properties:
                  data:
                    properties:
                      next_cursor:
                        nullable: true
                      strings:
                        items:
                          properties:
                            char_count:
                              type: integer
                            context_notes:
                              type: string
                            created_at:
                              type: string
                            filter_template_uid:
                              nullable: true
                            is_plural:
                              type: boolean
                            key:
                              type: string
                            normalized_value:
                              type: string
                            placeholder_type:
                              type: string
                            placeholders:
                              items:
                                type: string
                              type: array
                            plural_rules:
                              nullable: true
                            raw_value:
                              type: string
                            source_file:
                              type: string
                            source_format:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                            word_count:
                              type: integer
                            word_count_method:
                              type: string
                          type: object
                        type: array
                      total_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: List strings in a set with cursor pagination and optional filters.
      tags:
      - String Manager
    post:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              context_notes: Shown on the home screen
              filter_template_uid: null
              key: home.welcome_title
              raw_value: Welcome, {name}!
              source_file: home.json
            schema:
              properties:
                context_notes:
                  type: string
                filter_template_uid:
                  nullable: true
                key:
                  type: string
                raw_value:
                  type: string
                source_file:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  string:
                    char_count: 16
                    context_notes: Shown on the home screen
                    created_at: '2026-07-17T12:00:00+00:00'
                    filter_template_uid: null
                    is_plural: false
                    key: home.welcome_title
                    normalized_value: Welcome, {0}!
                    placeholder_type: icu
                    placeholders:
                    - '{name}'
                    plural_rules: null
                    raw_value: Welcome, {name}!
                    source_file: home.json
                    source_format: json
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    updated_at: '2026-07-17T12:00:00+00:00'
                    word_count: 2
                    word_count_method: icu
              schema:
                properties:
                  data:
                    properties:
                      string:
                        properties:
                          char_count:
                            type: integer
                          context_notes:
                            type: string
                          created_at:
                            type: string
                          filter_template_uid:
                            nullable: true
                          is_plural:
                            type: boolean
                          key:
                            type: string
                          normalized_value:
                            type: string
                          placeholder_type:
                            type: string
                          placeholders:
                            items:
                              type: string
                            type: array
                          plural_rules:
                            nullable: true
                          raw_value:
                            type: string
                          source_file:
                            type: string
                          source_format:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                          word_count:
                            type: integer
                          word_count_method:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Create a new string entry.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/{str_uid}/:
    delete:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  status: deleted
              schema:
                properties:
                  data:
                    properties:
                      status:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Soft-delete a string entry.
      tags:
      - String Manager
    get:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  string:
                    char_count: 16
                    context_notes: Shown on the home screen
                    created_at: '2026-07-17T12:00:00+00:00'
                    filter_template_uid: null
                    is_plural: false
                    key: home.welcome_title
                    normalized_value: Welcome, {0}!
                    placeholder_type: icu
                    placeholders:
                    - '{name}'
                    plural_rules: null
                    raw_value: Welcome, {name}!
                    source_file: home.json
                    source_format: json
                    translations:
                    - char_count: 18
                      is_reviewed: false
                      locale_code: fr-FR
                      normalized_value: Bienvenue, {0} !
                      raw_value: Bienvenue, {name} !
                      uid: d4c3b2a1-f6e5-4b7a-9d8c-1f0e3a2b5c4d
                      updated_at: '2026-07-17T12:05:00+00:00'
                      word_count: 2
                      word_count_method: icu
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    updated_at: '2026-07-17T12:00:00+00:00'
                    word_count: 2
                    word_count_method: icu
              schema:
                properties:
                  data:
                    properties:
                      string:
                        properties:
                          char_count:
                            type: integer
                          context_notes:
                            type: string
                          created_at:
                            type: string
                          filter_template_uid:
                            nullable: true
                          is_plural:
                            type: boolean
                          key:
                            type: string
                          normalized_value:
                            type: string
                          placeholder_type:
                            type: string
                          placeholders:
                            items:
                              type: string
                            type: array
                          plural_rules:
                            nullable: true
                          raw_value:
                            type: string
                          source_file:
                            type: string
                          source_format:
                            type: string
                          translations:
                            items:
                              properties:
                                char_count:
                                  type: integer
                                is_reviewed:
                                  type: boolean
                                locale_code:
                                  type: string
                                normalized_value:
                                  type: string
                                raw_value:
                                  type: string
                                uid:
                                  type: string
                                updated_at:
                                  type: string
                                word_count:
                                  type: integer
                                word_count_method:
                                  type: string
                              type: object
                            type: array
                          uid:
                            type: string
                          updated_at:
                            type: string
                          word_count:
                            type: integer
                          word_count_method:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Return a string with all its translations.
      tags:
      - String Manager
    patch:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              context_notes: Shown on the home screen
              key: home.welcome_title
              raw_value: Welcome back, {name}!
              source_file: home.json
            schema:
              properties:
                context_notes:
                  type: string
                key:
                  type: string
                raw_value:
                  type: string
                source_file:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  string:
                    char_count: 16
                    context_notes: Shown on the home screen
                    created_at: '2026-07-17T12:00:00+00:00'
                    filter_template_uid: null
                    is_plural: false
                    key: home.welcome_title
                    normalized_value: Welcome, {0}!
                    placeholder_type: icu
                    placeholders:
                    - '{name}'
                    plural_rules: null
                    raw_value: Welcome, {name}!
                    source_file: home.json
                    source_format: json
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    updated_at: '2026-07-17T12:00:00+00:00'
                    word_count: 2
                    word_count_method: icu
              schema:
                properties:
                  data:
                    properties:
                      string:
                        properties:
                          char_count:
                            type: integer
                          context_notes:
                            type: string
                          created_at:
                            type: string
                          filter_template_uid:
                            nullable: true
                          is_plural:
                            type: boolean
                          key:
                            type: string
                          normalized_value:
                            type: string
                          placeholder_type:
                            type: string
                          placeholders:
                            items:
                              type: string
                            type: array
                          plural_rules:
                            nullable: true
                          raw_value:
                            type: string
                          source_file:
                            type: string
                          source_format:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                          word_count:
                            type: integer
                          word_count_method:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Update a string entry.  Creates a version snapshot if raw_value changes.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/{str_uid}/comments:
    post:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Please double-check the formal register here.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  comment:
                    author: Ada Lovelace
                    body: Please double-check the formal register here.
                    created_at: '2026-07-17T12:15:00+00:00'
                    uid: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
              schema:
                properties:
                  data:
                    properties:
                      comment:
                        properties:
                          author:
                            type: string
                          body:
                            type: string
                          created_at:
                            type: string
                          uid:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Add a comment to a string entry.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/{str_uid}/embed:
    get:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  embedded: true
                  status: ok
              schema:
                properties:
                  data:
                    properties:
                      embedded:
                        type: boolean
                      status:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Trigger embedding computation for a single string entry.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/{str_uid}/similar:
    get:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  similar:
                  - key: home.welcome_back
                    raw_value: Welcome back!
                    similarity: 0.92
                    uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    properties:
                      similar:
                        items:
                          properties:
                            key:
                              type: string
                            raw_value:
                              type: string
                            similarity:
                              type: number
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Return up to *limit* similar strings using pgvector cosine similarity.
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/strings/{str_uid}/translations/{locale_code}:
    put:
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: str_uid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      - in: path
        name: locale_code
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              value: Bienvenue, {name} !
            schema:
              properties:
                value:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  translation:
                    char_count: 18
                    is_reviewed: false
                    locale_code: fr-FR
                    normalized_value: Bienvenue, {0} !
                    raw_value: Bienvenue, {name} !
                    uid: d4c3b2a1-f6e5-4b7a-9d8c-1f0e3a2b5c4d
                    updated_at: '2026-07-17T12:05:00+00:00'
                    word_count: 2
                    word_count_method: icu
              schema:
                properties:
                  data:
                    properties:
                      translation:
                        properties:
                          char_count:
                            type: integer
                          is_reviewed:
                            type: boolean
                          locale_code:
                            type: string
                          normalized_value:
                            type: string
                          raw_value:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                          word_count:
                            type: integer
                          word_count_method:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Create or update a translation for (string, locale).
      tags:
      - String Manager
  /account/strings/{account_uuid}/api/v1/string-sets/{set_uid}/upload:
    post:
      description: "Multipart fields:\n    file                 – the file to import\
        \ (required)\n    locale_code          – BCP-47 code; if omitted, imports\
        \ as primary language\n    conflict_mode        – 'skip' or 'update' (default:\
        \ 'update')\n    filter_template_uid  – UID of a FilterTemplate to apply during\
        \ parsing\n    format_override      – force a file format (e.g. 'xml', 'dita',\
        \ 'html_blocks')\n                           regardless of the filename extension"
      parameters:
      - in: path
        name: account_uuid
        required: true
        schema:
          type: string
      - in: path
        name: set_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  format: json
                  imported: 12
                  new: 10
                  skipped: 0
                  updated: 2
                  upload_uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
              schema:
                properties:
                  data:
                    properties:
                      format:
                        type: string
                      imported:
                        type: integer
                      new:
                        type: integer
                      skipped:
                        type: integer
                      updated:
                        type: integer
                      upload_uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      servers:
      - url: https://api.totalctrl.app
      summary: Import strings from an uploaded file.
      tags:
      - String Manager
  /accounting/bills:
    get:
      description: List bills, optionally filtered by status.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - awaiting_payment
          - paid
          - voided
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Bill'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List bills
      tags:
      - Accounting
  /accounting/bills/{bill_id}:
    get:
      description: Get a single bill by ID.
      parameters:
      - in: path
        name: bill_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Bill'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get bill
      tags:
      - Accounting
  /accounting/budgets:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  currency: USD
                  fiscal_year: 2026
                  lines:
                  - actual: 15000
                    budget: 20000
                    code: '4000'
                    name: Sales
                    type: revenue
                    variance: -5000
              schema:
                properties:
                  data:
                    properties:
                      currency:
                        type: string
                      fiscal_year:
                        type: integer
                      lines:
                        items:
                          properties:
                            actual:
                              type: number
                            budget:
                              type: number
                            code:
                              type: string
                            name:
                              type: string
                            type:
                              type: string
                            variance:
                              type: number
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Budget vs actual for ?year=YYYY (default current year).
      tags:
      - Accounting
  /accounting/contacts:
    get:
      description: List contacts (customers/suppliers).
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: contact_type
        schema:
          enum:
          - customer
          - supplier
          - both
          type: string
      - in: query
        name: search
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/AccountingContact'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List accounting contacts
      tags:
      - Accounting
    post:
      description: Create a new accounting contact.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                contact_type:
                  enum:
                  - customer
                  - supplier
                  - both
                  type: string
                currency:
                  default: USD
                  type: string
                email:
                  type: string
                name:
                  type: string
                phone:
                  type: string
              required:
              - name
              - contact_type
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AccountingContact'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create accounting contact
      tags:
      - Accounting
  /accounting/contacts/{contact_id}:
    get:
      description: Get a single accounting contact by ID.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AccountingContact'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get accounting contact
      tags:
      - Accounting
  /accounting/expenses:
    get:
      description: List expense claims, optionally filtered by status.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - submitted
          - approved
          - paid
          - rejected
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Expense'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List expenses
      tags:
      - Accounting
  /accounting/inventory:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - avg_cost: 4.5
                  id: 1
                  name: Blue Widget
                  qty_on_hand: 120
                  sale_price: 9.99
                  sku: WIDGET-01
                  stock_value: 540
              schema:
                properties:
                  data:
                    items:
                      properties:
                        avg_cost:
                          type: number
                        id:
                          type: integer
                        name:
                          type: string
                        qty_on_hand:
                          type: number
                        sale_price:
                          type: number
                        sku:
                          type: string
                        stock_value:
                          type: number
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Inventory items with quantity on hand and stock value.
      tags:
      - Accounting
  /accounting/invoices:
    get:
      description: List invoices, optionally filtered by status.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - sent
          - paid
          - overdue
          - voided
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Invoice'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List invoices
      tags:
      - Accounting
  /accounting/invoices/{inv_id}:
    get:
      description: Get a single invoice with line items.
      parameters:
      - in: path
        name: inv_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get invoice
      tags:
      - Accounting
  /accounting/invoices/{inv_id}/pay:
    post:
      description: Mark an invoice as paid.
      parameters:
      - in: path
        name: inv_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount_paid:
                  type: number
                paid_date:
                  format: date
                  type: string
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Mark invoice paid
      tags:
      - Accounting
  /accounting/metrics/mrr-arr:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  active: 12
                  arr: 50400
                  connected: true
                  mrr: 4200
              schema:
                properties:
                  data:
                    properties:
                      active:
                        type: integer
                      arr:
                        type: number
                      connected:
                        type: boolean
                      mrr:
                        type: number
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Live MRR/ARR from active Stripe subscriptions.
      tags:
      - Accounting
  /accounting/reports/balance-sheet:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assets:
                  - balance: 20000
                    code: '1000'
                    name: Cash
                  currency: USD
                  current_earnings: 6800
                  equity:
                  - balance: 8200
                    code: '3000'
                    name: Owner Equity
                  liabilities:
                  - balance: 5000
                    code: '2000'
                    name: Accounts Payable
                  to_date: '2026-07-17'
                  total_assets: 20000
                  total_equity: 15000
                  total_liabilities: 5000
              schema:
                properties:
                  data:
                    properties:
                      assets:
                        items:
                          properties:
                            balance:
                              type: number
                            code:
                              type: string
                            name:
                              type: string
                          type: object
                        type: array
                      currency:
                        type: string
                      current_earnings:
                        type: number
                      equity:
                        items:
                          properties:
                            balance:
                              type: number
                            code:
                              type: string
                            name:
                              type: string
                          type: object
                        type: array
                      liabilities:
                        items:
                          properties:
                            balance:
                              type: number
                            code:
                              type: string
                            name:
                              type: string
                          type: object
                        type: array
                      to_date:
                        type: string
                      total_assets:
                        type: number
                      total_equity:
                        type: number
                      total_liabilities:
                        type: number
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Balance sheet as of ?to_date (default today). Base currency.
      tags:
      - Accounting
  /accounting/reports/profit-loss:
    get:
      description: Get P&L report for a date range.
      parameters:
      - in: query
        name: from_date
        schema:
          format: date
          type: string
      - in: query
        name: to_date
        schema:
          format: date
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProfitLoss'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Profit & Loss report
      tags:
      - Accounting
  /accounting/reports/tax-liability:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  accounts:
                  - code: '2200'
                    collected: 1500
                    name: Sales Tax Payable
                    net: 1200
                    reclaimed: 300
                  currency: USD
                  from_date: '2026-01-01'
                  to_date: '2026-07-17'
                  totals:
                    collected: 1500
                    net: 1200
                    reclaimed: 300
              schema:
                properties:
                  data:
                    properties:
                      accounts:
                        items:
                          properties:
                            code:
                              type: string
                            collected:
                              type: number
                            name:
                              type: string
                            net:
                              type: number
                            reclaimed:
                              type: number
                          type: object
                        type: array
                      currency:
                        type: string
                      from_date:
                        type: string
                      to_date:
                        type: string
                      totals:
                        properties:
                          collected:
                            type: number
                          net:
                            type: number
                          reclaimed:
                            type: number
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Tax liability (collected − reclaimed = net owed) for ?from_date&?to_date.
      tags:
      - Accounting
  /accounting/reports/trial-balance:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  accounts:
                  - code: '4000'
                    credit: 15000
                    debit: 0
                    name: Sales
                    type: revenue
                  currency: USD
                  to_date: '2026-07-17'
                  total_credit: 15000
                  total_debit: 15000
              schema:
                properties:
                  data:
                    properties:
                      accounts:
                        items:
                          properties:
                            code:
                              type: string
                            credit:
                              type: number
                            debit:
                              type: number
                            name:
                              type: string
                            type:
                              type: string
                          type: object
                        type: array
                      currency:
                        type: string
                      to_date:
                        type: string
                      total_credit:
                        type: number
                      total_debit:
                        type: number
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trial balance as of ?to_date=YYYY-MM-DD (default today). Base currency.
      tags:
      - Accounting
  /agent-inbox/connectors:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - connector_type: github
                  created_at: '2026-02-03T08:05:00+00:00'
                  display_name: My Connector
                  events_received: 0
                  is_active: true
                  last_synced_at: null
                  uid: con_3b1d7f9a2c5e
                  webhook_url: /webhooks/connector/abc123def456
              schema:
                properties:
                  data:
                    items:
                      properties:
                        connector_type:
                          type: string
                        created_at:
                          type: string
                        display_name:
                          type: string
                        events_received:
                          type: integer
                        is_active:
                          type: boolean
                        last_synced_at:
                          nullable: true
                        uid:
                          type: string
                        webhook_url:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List external connectors for the tenant.
      tags:
      - AI Agent & Knowledge
    post:
      description: 'JSON body: { "connector_type": "github", "display_name": "My Connector"
        }'
      requestBody:
        content:
          application/json:
            example:
              connector_type: github
              display_name: My Connector
            schema:
              properties:
                connector_type:
                  type: string
                display_name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  connector_type: github
                  created_at: '2026-02-03T08:05:00+00:00'
                  display_name: My Connector
                  events_received: 0
                  is_active: true
                  last_synced_at: null
                  uid: con_3b1d7f9a2c5e
                  webhook_url: /webhooks/connector/abc123def456
              schema:
                properties:
                  data:
                    properties:
                      connector_type:
                        type: string
                      created_at:
                        type: string
                      display_name:
                        type: string
                      events_received:
                        type: integer
                      is_active:
                        type: boolean
                      last_synced_at:
                        nullable: true
                      uid:
                        type: string
                      webhook_url:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new external connector.
      tags:
      - AI Agent & Knowledge
  /agent-inbox/items:
    get:
      description: 'Query params: status, priority, source_app, limit (default 25),
        offset (default 0)'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  items:
                  - actioned_at: null
                    created_at: '2026-02-03T08:00:00+00:00'
                    draft_content: null
                    expires_at: null
                    item_type: pr_review
                    priority: high
                    source_app: github
                    source_links: []
                    status: pending
                    suggested_action: approve
                    summary: A new pull request needs review.
                    title: 'Review PR #142'
                    uid: itm_7f3a9c2e5b1d
                    updated_at: '2026-02-03T08:00:00+00:00'
                  limit: 25
                  offset: 0
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            actioned_at:
                              nullable: true
                            created_at:
                              type: string
                            draft_content:
                              nullable: true
                            expires_at:
                              nullable: true
                            item_type:
                              type: string
                            priority:
                              type: string
                            source_app:
                              type: string
                            source_links:
                              items: {}
                              type: array
                            status:
                              type: string
                            suggested_action:
                              type: string
                            summary:
                              type: string
                            title:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List agent inbox items for the authenticated tenant.
      tags:
      - AI Agent & Knowledge
  /agent-inbox/items/{item_uid}:
    get:
      parameters:
      - in: path
        name: item_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  actioned_at: null
                  created_at: '2026-02-03T08:00:00+00:00'
                  draft_content: null
                  expires_at: null
                  item_type: pr_review
                  priority: high
                  source_app: github
                  source_links: []
                  status: pending
                  suggested_action: approve
                  summary: A new pull request needs review.
                  title: 'Review PR #142'
                  uid: itm_7f3a9c2e5b1d
                  updated_at: '2026-02-03T08:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      actioned_at:
                        nullable: true
                      created_at:
                        type: string
                      draft_content:
                        nullable: true
                      expires_at:
                        nullable: true
                      item_type:
                        type: string
                      priority:
                        type: string
                      source_app:
                        type: string
                      source_links:
                        items: {}
                        type: array
                      status:
                        type: string
                      suggested_action:
                        type: string
                      summary:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single agent inbox item by uid.
      tags:
      - AI Agent & Knowledge
  /agent-inbox/items/{item_uid}/approve:
    post:
      parameters:
      - in: path
        name: item_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  actioned_at: null
                  created_at: '2026-02-03T08:00:00+00:00'
                  draft_content: null
                  expires_at: null
                  item_type: pr_review
                  priority: high
                  source_app: github
                  source_links: []
                  status: pending
                  suggested_action: approve
                  summary: A new pull request needs review.
                  title: 'Review PR #142'
                  uid: itm_7f3a9c2e5b1d
                  updated_at: '2026-02-03T08:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      actioned_at:
                        nullable: true
                      created_at:
                        type: string
                      draft_content:
                        nullable: true
                      expires_at:
                        nullable: true
                      item_type:
                        type: string
                      priority:
                        type: string
                      source_app:
                        type: string
                      source_links:
                        items: {}
                        type: array
                      status:
                        type: string
                      suggested_action:
                        type: string
                      summary:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Approve an agent inbox item.
      tags:
      - AI Agent & Knowledge
  /agent-inbox/items/{item_uid}/dismiss:
    post:
      parameters:
      - in: path
        name: item_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  actioned_at: null
                  created_at: '2026-02-03T08:00:00+00:00'
                  draft_content: null
                  expires_at: null
                  item_type: pr_review
                  priority: high
                  source_app: github
                  source_links: []
                  status: pending
                  suggested_action: approve
                  summary: A new pull request needs review.
                  title: 'Review PR #142'
                  uid: itm_7f3a9c2e5b1d
                  updated_at: '2026-02-03T08:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      actioned_at:
                        nullable: true
                      created_at:
                        type: string
                      draft_content:
                        nullable: true
                      expires_at:
                        nullable: true
                      item_type:
                        type: string
                      priority:
                        type: string
                      source_app:
                        type: string
                      source_links:
                        items: {}
                        type: array
                      status:
                        type: string
                      suggested_action:
                        type: string
                      summary:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Dismiss an agent inbox item.
      tags:
      - AI Agent & Knowledge
  /agent-inbox/jobs:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - ai_units_used: 12
                  created_at: '2026-02-03T08:10:00+00:00'
                  error_message: null
                  finished_at: '2026-02-03T08:10:45+00:00'
                  items_created: 3
                  items_skipped: 1
                  job_type: scan
                  result_summary: Scan complete.
                  started_at: '2026-02-03T08:10:00+00:00'
                  status: completed
                  trigger: cron
                  uid: job_5e2c8a1f7b3d
              schema:
                properties:
                  data:
                    items:
                      properties:
                        ai_units_used:
                          type: integer
                        created_at:
                          type: string
                        error_message:
                          nullable: true
                        finished_at:
                          type: string
                        items_created:
                          type: integer
                        items_skipped:
                          type: integer
                        job_type:
                          type: string
                        result_summary:
                          type: string
                        started_at:
                          type: string
                        status:
                          type: string
                        trigger:
                          type: string
                        uid:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List recent agent jobs for the tenant (newest first, max 50).
      tags:
      - AI Agent & Knowledge
  /agent/agents:
    get:
      description: "Returns: [{id, name, tagline, is_enabled, public_key, total_chunks,\n\
        \            conversation_count, created_at}]"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  agents:
                  - color: '#4F46E5'
                    conversation_count: 42
                    created_at: '2026-07-01T12:30:00+00:00'
                    id: 1
                    is_enabled: true
                    min_score: 0.75
                    name: Support Bot
                    public_key: pub_example_key
                    tagline: Ask me anything
                    top_k: 5
                    total_chunks: 128
                    welcome_message: Hi! How can I help you today?
                    widget_position: bottom-right
              schema:
                properties:
                  data:
                    properties:
                      agents:
                        items:
                          properties:
                            color:
                              type: string
                            conversation_count:
                              type: integer
                            created_at:
                              type: string
                            id:
                              type: integer
                            is_enabled:
                              type: boolean
                            min_score:
                              type: number
                            name:
                              type: string
                            public_key:
                              type: string
                            tagline:
                              type: string
                            top_k:
                              type: integer
                            total_chunks:
                              type: integer
                            welcome_message:
                              type: string
                            widget_position:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all AI Support Agents for this account.
      tags:
      - AI Agent & Knowledge
  /agent/agents/{agent_id}:
    get:
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#4F46E5'
                  conversation_count: 42
                  created_at: '2026-07-01T12:30:00+00:00'
                  id: 1
                  is_enabled: true
                  min_score: 0.75
                  name: Support Bot
                  public_key: pub_example_key
                  tagline: Ask me anything
                  top_k: 5
                  total_chunks: 128
                  welcome_message: Hi! How can I help you today?
                  widget_position: bottom-right
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      conversation_count:
                        type: integer
                      created_at:
                        type: string
                      id:
                        type: integer
                      is_enabled:
                        type: boolean
                      min_score:
                        type: number
                      name:
                        type: string
                      public_key:
                        type: string
                      tagline:
                        type: string
                      top_k:
                        type: integer
                      total_chunks:
                        type: integer
                      welcome_message:
                        type: string
                      widget_position:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single AI Support Agent by ID.
      tags:
      - AI Agent & Knowledge
  /agent/agents/{agent_id}/conversations:
    get:
      description: "Query params:\n  status  — filter by status: active | resolved\
        \ | escalated\n  limit   — max results (default 50, max 200)\n  offset  —\
        \ pagination offset"
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  agent_id: 1
                  conversations:
                  - created_at: '2026-07-15T09:00:00+00:00'
                    id: 1
                    message_count: 4
                    session_id: sess_9f8e7d6c
                    status: active
                    updated_at: '2026-07-15T09:05:00+00:00'
                    visitor_email: jane@example.com
                    visitor_name: Jane Doe
                  limit: 50
                  offset: 0
                  total: 42
              schema:
                properties:
                  data:
                    properties:
                      agent_id:
                        type: integer
                      conversations:
                        items:
                          properties:
                            created_at:
                              type: string
                            id:
                              type: integer
                            message_count:
                              type: integer
                            session_id:
                              type: string
                            status:
                              type: string
                            updated_at:
                              type: string
                            visitor_email:
                              type: string
                            visitor_name:
                              type: string
                          type: object
                        type: array
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List conversations for an AI Support Agent.
      tags:
      - AI Agent & Knowledge
  /agent/agents/{agent_id}/conversations/{convo_id}:
    get:
      parameters:
      - in: path
        name: convo_id
        required: true
        schema:
          type: string
      - in: path
        name: agent_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-15T09:00:00+00:00'
                  id: 1
                  message_count: 2
                  messages:
                  - content: How do I reset my password?
                    created_at: '2026-07-15T09:00:00+00:00'
                    id: 1
                    role: user
                    sources_used: null
                  - content: You can reset it from the login page.
                    created_at: '2026-07-15T09:00:05+00:00'
                    id: 2
                    role: assistant
                    sources_used:
                    - doc-42
                    - doc-88
                  session_id: sess_9f8e7d6c
                  status: active
                  updated_at: '2026-07-15T09:05:00+00:00'
                  visitor_email: jane@example.com
                  visitor_name: Jane Doe
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      id:
                        type: integer
                      message_count:
                        type: integer
                      messages:
                        items:
                          properties:
                            content:
                              type: string
                            created_at:
                              type: string
                            id:
                              type: integer
                            role:
                              type: string
                            sources_used:
                              nullable: true
                          type: object
                        type: array
                      session_id:
                        type: string
                      status:
                        type: string
                      updated_at:
                        type: string
                      visitor_email:
                        type: string
                      visitor_name:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a conversation with its full message transcript.
      tags:
      - AI Agent & Knowledge
  /agents:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  agents:
                  - agent_type: inbox
                    approval_threshold: high_only
                    color: '#6366f1'
                    icon: bi-robot
                    is_active: true
                    name: Support Triage
                    scope:
                    - support
                    - crm
                    uid: a1b2c3d4
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      agents:
                        items:
                          properties:
                            agent_type:
                              type: string
                            approval_threshold:
                              type: string
                            color:
                              type: string
                            icon:
                              type: string
                            is_active:
                              type: boolean
                            name:
                              type: string
                            scope:
                              items:
                                type: string
                              type: array
                            uid:
                              type: string
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all named agents for the tenant.
      tags:
      - AI Agent & Knowledge
    post:
      requestBody:
        content:
          application/json:
            example:
              approval_threshold: high_only
              color: '#6366f1'
              icon: bi-robot
              name: Support Triage
              scope:
              - support
              - crm
              system_prompt: You triage inbound support tickets.
            schema:
              properties:
                approval_threshold:
                  type: string
                color:
                  type: string
                icon:
                  type: string
                name:
                  type: string
                scope:
                  items:
                    type: string
                  type: array
                system_prompt:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  name: Support Triage
                  uid: a1b2c3d4
              schema:
                properties:
                  data:
                    properties:
                      name:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a named agent.
      tags:
      - AI Agent & Knowledge
  /agents/{agent_uid}:
    delete:
      parameters:
      - in: path
        name: agent_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: DELETE /api/v1/agents/<uid>
      tags:
      - AI Agent & Knowledge
    get:
      parameters:
      - in: path
        name: agent_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  agent_type: inbox
                  approval_threshold: high_only
                  color: '#6366f1'
                  icon: bi-robot
                  is_active: true
                  name: Support Triage
                  scope:
                  - support
                  - crm
                  system_prompt: You triage inbound support tickets.
                  uid: a1b2c3d4
              schema:
                properties:
                  data:
                    properties:
                      agent_type:
                        type: string
                      approval_threshold:
                        type: string
                      color:
                        type: string
                      icon:
                        type: string
                      is_active:
                        type: boolean
                      name:
                        type: string
                      scope:
                        items:
                          type: string
                        type: array
                      system_prompt:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: GET /api/v1/agents/<uid>
      tags:
      - AI Agent & Knowledge
    patch:
      parameters:
      - in: path
        name: agent_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              is_active: false
              name: Support Triage v2
            schema:
              properties:
                is_active:
                  type: boolean
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  uid: a1b2c3d4
                  updated: true
              schema:
                properties:
                  data:
                    properties:
                      uid:
                        type: string
                      updated:
                        type: boolean
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: PATCH /api/v1/agents/<uid>
      tags:
      - AI Agent & Knowledge
  /analytics/dashboards:
    get:
      description: "Response fields per dashboard:\n  id, name, description, panel_count,\
        \ created_at, updated_at"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: 2026-07-01T12:00:00+00:00Z
                  description: Monthly revenue and signups
                  id: 9b1c8f2a-4d3e-4a1b-8c2d-1f0e9a7b6c5d
                  name: Revenue Overview
                  panel_count: 3
                  updated_at: 2026-07-10T09:30:00+00:00Z
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        description:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        panel_count:
                          type: integer
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List custom analytics dashboards for the authenticated tenant.
      tags:
      - Analytics
    post:
      description: "Request body (JSON):\n  name        string  required  Dashboard\
        \ title (max 200 chars)\n  description string  optional  Dashboard description\
        \ (max 1000 chars)\n\nReturns the created dashboard object."
      requestBody:
        content:
          application/json:
            example:
              description: Monthly revenue and signups
              name: Revenue Overview
            schema:
              properties:
                description:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: 2026-07-01T12:00:00+00:00Z
                  description: Monthly revenue and signups
                  id: 9b1c8f2a-4d3e-4a1b-8c2d-1f0e9a7b6c5d
                  name: Revenue Overview
                  panel_count: 3
                  updated_at: 2026-07-10T09:30:00+00:00Z
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: string
                      name:
                        type: string
                      panel_count:
                        type: integer
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new analytics dashboard.
      tags:
      - Analytics
  /analytics/dashboards/{dash_uuid}:
    delete:
      parameters:
      - in: path
        name: dash_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: 9b1c8f2a-4d3e-4a1b-8c2d-1f0e9a7b6c5d
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an analytics dashboard and all its panels.
      tags:
      - Analytics
    get:
      description: "Response:\n  dashboard fields + panels array (each with id, title,\
        \ source, metric,\n  chart_type, params, position, width)"
      parameters:
      - in: path
        name: dash_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: 2026-07-01T12:00:00+00:00Z
                  description: Monthly revenue and signups
                  id: 9b1c8f2a-4d3e-4a1b-8c2d-1f0e9a7b6c5d
                  name: Revenue Overview
                  panel_count: 3
                  panels:
                  - chart_type: line
                    id: 3f2a1b0c-9d8e-4c7b-6a5f-4e3d2c1b0a9f
                    metric: newsletter_signups
                    params:
                      days: 30
                    position: 0
                    source: native
                    title: Newsletter Signups
                    width: col-md-6
                  updated_at: 2026-07-10T09:30:00+00:00Z
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: string
                      name:
                        type: string
                      panel_count:
                        type: integer
                      panels:
                        items:
                          properties:
                            chart_type:
                              type: string
                            id:
                              type: string
                            metric:
                              type: string
                            params:
                              properties:
                                days:
                                  type: integer
                              type: object
                            position:
                              type: integer
                            source:
                              type: string
                            title:
                              type: string
                            width:
                              type: string
                          type: object
                        type: array
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single analytics dashboard and all its panels.
      tags:
      - Analytics
  /analytics/dashboards/{dash_uuid}/panels:
    post:
      description: "Request body (JSON):\n  title       string   optional  Panel title\
        \ (max 200 chars)\n  source      string   required  One of: native, snowflake,\
        \ bigquery, datadog, google_analytics\n  metric      string   required  Metric\
        \ ID (native) or SQL query / metric expression\n  chart_type  string   required\
        \  One of: line, bar, doughnut, pie, kpi\n  params      object   optional\
        \  Driver-specific hints (e.g. {days: 30}, {hours: 24})\n  width       string\
        \   optional  CSS column class: col-md-4 | col-md-6 | col-md-8 | col-md-12\n\
        \nReturns the created panel object."
      parameters:
      - in: path
        name: dash_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              chart_type: line
              metric: newsletter_signups
              params:
                days: 30
              source: native
              title: Newsletter Signups
              width: col-md-6
            schema:
              properties:
                chart_type:
                  type: string
                metric:
                  type: string
                params:
                  properties:
                    days:
                      type: integer
                  type: object
                source:
                  type: string
                title:
                  type: string
                width:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  chart_type: line
                  id: 3f2a1b0c-9d8e-4c7b-6a5f-4e3d2c1b0a9f
                  metric: newsletter_signups
                  params:
                    days: 30
                  position: 0
                  source: native
                  title: Newsletter Signups
                  width: col-md-6
              schema:
                properties:
                  data:
                    properties:
                      chart_type:
                        type: string
                      id:
                        type: string
                      metric:
                        type: string
                      params:
                        properties:
                          days:
                            type: integer
                        type: object
                      position:
                        type: integer
                      source:
                        type: string
                      title:
                        type: string
                      width:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add a panel to an analytics dashboard.
      tags:
      - Analytics
  /analytics/dashboards/{dash_uuid}/panels/{panel_uuid}:
    delete:
      parameters:
      - in: path
        name: dash_uuid
        required: true
        schema:
          type: string
      - in: path
        name: panel_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: 3f2a1b0c-9d8e-4c7b-6a5f-4e3d2c1b0a9f
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Remove a panel from an analytics dashboard.
      tags:
      - Analytics
  /analytics/metrics:
    get:
      description: 'Response: array of {id, name, group, chart_type} objects.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - chart_type: line
                  group: Newsletter
                  id: newsletter_signups
                  name: Newsletter Signups
              schema:
                properties:
                  data:
                    items:
                      properties:
                        chart_type:
                          type: string
                        group:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all available native analytics metrics.
      tags:
      - Analytics
  /analytics/query:
    post:
      description: "Only ``native`` source is available via the API (SQL execution\
        \ against\nexternal warehouses requires an active browser session for OAuth).\
        \  To\nquery Snowflake or BigQuery programmatically, use those services' own\
        \ APIs.\n\nRequest body (JSON):\n  source  string  required  Must be \"native\"\
        \n  metric  string  required  Native metric ID (see GET /analytics/metrics\
        \ for full list)\n  params  object  optional  Accepted keys: days (7|30|90),\
        \ limit\n\nResponse:\n  value   number|string  Scalar result (for KPI metrics)\n\
        \  data    object         Chart.js-compatible dataset (for chart metrics)\n\
        \  type    string         \"kpi\" | \"line\" | \"bar\" | \"doughnut\""
      requestBody:
        content:
          application/json:
            example:
              metric: newsletter_signups
              params:
                days: 30
              source: native
            schema:
              properties:
                metric:
                  type: string
                params:
                  properties:
                    days:
                      type: integer
                  type: object
                source:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  type: kpi
                  value: 1234
              schema:
                properties:
                  data:
                    properties:
                      type:
                        type: string
                      value:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Run an analytics query and return the results.
      tags:
      - Analytics
  /assets:
    get:
      description: 'Returns a paginated list of digital assets for the account.


        Filter by `asset_type` (image, video, audio, document, other), `folder_id`,
        `lang` (BCP-47 locale code, e.g. `en-US`), or full-text `q`.


        **Webhook events:** `asset.uploaded`'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - description: Search title or tags.
        in: query
        name: q
        schema:
          type: string
      - in: query
        name: asset_type
        schema:
          enum:
          - image
          - video
          - audio
          - document
          - other
          type: string
      - description: Filter to a specific folder.
        in: query
        name: folder_id
        schema:
          type: integer
      - description: Filter by primary_language locale code (e.g. en-US).
        in: query
        name: lang
        schema:
          type: string
      - in: query
        name: permission
        schema:
          enum:
          - private
          - team
          - public
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Asset'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List assets
      tags:
      - Assets
    post:
      description: 'Send as multipart/form-data with a `file` part, plus optional
        form fields:

        title, description, permission (private|restricted|public), folder_id, tags

        (comma-separated), content_type, rights_holder, license_type.'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  ai_alt_text: A field of tulips at sunrise.
                  asset_type: image
                  content_type: Social
                  created_at: '2026-07-17T12:00:00+00:00'
                  custom_metadata:
                    Campaign: Spring 2026
                  description: Homepage hero for the spring campaign.
                  download_url: https://api.totalctrl.app/d/abc123def456
                  expires_at: null
                  file_size: 277.5 KB
                  file_size_bytes: 284120
                  folder_id: 3
                  folder_name: Brand
                  id: 42
                  is_expired: false
                  is_primary_language: true
                  language_group_id: null
                  license_type: All rights reserved
                  mime_type: image/png
                  original_filename: spring-hero.png
                  permission: public
                  primary_language: en-US
                  rights_holder: Acme Inc.
                  tags:
                  - spring
                  - campaign
                  title: Spring hero banner
                  updated_at: '2026-07-17T12:05:00+00:00'
                  uploaded_by: Ada Lovelace
                  version: 1
                  version_count: 1
              schema:
                properties:
                  data:
                    properties:
                      ai_alt_text:
                        type: string
                      asset_type:
                        type: string
                      content_type:
                        type: string
                      created_at:
                        type: string
                      custom_metadata:
                        properties:
                          Campaign:
                            type: string
                        type: object
                      description:
                        type: string
                      download_url:
                        type: string
                      expires_at:
                        nullable: true
                      file_size:
                        type: string
                      file_size_bytes:
                        type: integer
                      folder_id:
                        type: integer
                      folder_name:
                        type: string
                      id:
                        type: integer
                      is_expired:
                        type: boolean
                      is_primary_language:
                        type: boolean
                      language_group_id:
                        nullable: true
                      license_type:
                        type: string
                      mime_type:
                        type: string
                      original_filename:
                        type: string
                      permission:
                        type: string
                      primary_language:
                        type: string
                      rights_holder:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                      uploaded_by:
                        type: string
                      version:
                        type: integer
                      version_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Upload a new asset.
      tags:
      - Assets
  /assets/collections:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  collections:
                  - allow_downloads: true
                    id: 1
                    is_published: true
                    item_count: 8
                    name: Press kit
                    public_url: https://da.totalctrl.app/c/press-kit
                    slug: press-kit
                    uuid: c0ffee00-...
                    visibility: public
                  count: 1
              schema:
                properties:
                  data:
                    properties:
                      collections:
                        items:
                          properties:
                            allow_downloads:
                              type: boolean
                            id:
                              type: integer
                            is_published:
                              type: boolean
                            item_count:
                              type: integer
                            name:
                              type: string
                            public_url:
                              type: string
                            slug:
                              type: string
                            uuid:
                              type: string
                            visibility:
                              type: string
                          type: object
                        type: array
                      count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List shared asset collections.
      tags:
      - Assets
  /assets/collections/{collection_uuid}/items:
    post:
      description: 'Body (JSON): { "asset_id": 123 }'
      parameters:
      - in: path
        name: collection_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              asset_id: 123
            schema:
              properties:
                asset_id:
                  type: integer
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  asset_id: 123
                  collection_uuid: c0ffee00-1111-2222-3333-444455556666
                  item_count: 8
              schema:
                properties:
                  data:
                    properties:
                      asset_id:
                        type: integer
                      collection_uuid:
                        type: string
                      item_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add an asset to a shared collection.
      tags:
      - Assets
  /assets/folders:
    get:
      description: Return all asset folders for the account in a flat list ordered
        by name.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/AssetFolder'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List folders
      tags:
      - Assets
    post:
      description: Create a new asset folder. Optionally nest it under a `parent_id`.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                parent_id:
                  nullable: true
                  type: integer
              required:
              - name
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AssetFolder'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create folder
      tags:
      - Assets
  /assets/folders/{folder_id}:
    delete:
      parameters:
      - in: path
        name: folder_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: 5
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an empty folder (must contain no assets or subfolders).
      tags:
      - Assets
    patch:
      parameters:
      - in: path
        name: folder_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              color: '#6b7280'
              name: Q3 Campaign
            schema:
              properties:
                color:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#6b7280'
                  id: 5
                  name: Q3 Campaign
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      id:
                        type: integer
                      name:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Rename / recolor a folder. Body (JSON): { name?, color? }.'
      tags:
      - Assets
  /assets/languages:
    get:
      description: 'Return all languages enabled for Digital Assets in this workspace.


        Use the `locale_code` values when setting `primary_language` on assets or
        filtering by `?lang=` on the list endpoint.'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/TenantLanguage'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List enabled languages
      tags:
      - Assets
  /assets/search:
    get:
      description: 'Query params: ?q= (required, natural-language query), ?limit=
        (default 20, max 50).

        Returns assets ranked by `relevance` (0-1).'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  query: spring banner
                  results:
                  - asset_type: image
                    created_at: '2026-07-17T12:00:00+00:00'
                    download_url: https://api.totalctrl.app/d/abc123def456
                    file_size: 277.5 KB
                    file_size_bytes: 284120
                    folder_id: 3
                    id: 42
                    is_expired: false
                    mime_type: image/png
                    permission: public
                    primary_language: en-US
                    relevance: 0.87
                    tags:
                    - spring
                    - campaign
                    title: Spring hero banner
                    version: 1
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      query:
                        type: string
                      results:
                        items:
                          properties:
                            asset_type:
                              type: string
                            created_at:
                              type: string
                            download_url:
                              type: string
                            file_size:
                              type: string
                            file_size_bytes:
                              type: integer
                            folder_id:
                              type: integer
                            id:
                              type: integer
                            is_expired:
                              type: boolean
                            mime_type:
                              type: string
                            permission:
                              type: string
                            primary_language:
                              type: string
                            relevance:
                              type: number
                            tags:
                              items:
                                type: string
                              type: array
                            title:
                              type: string
                            version:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Semantic (meaning-based) search of the asset library.
      tags:
      - Assets
  /assets/{asset_id}:
    delete:
      parameters:
      - in: path
        name: asset_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: 123
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an asset (and all its versions + cached renditions).
      tags:
      - Assets
    get:
      parameters:
      - in: path
        name: asset_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_alt_text: A field of tulips at sunrise.
                  asset_type: image
                  content_type: Social
                  created_at: '2026-07-17T12:00:00+00:00'
                  custom_metadata:
                    Campaign: Spring 2026
                  description: Homepage hero for the spring campaign.
                  download_url: https://api.totalctrl.app/d/abc123def456
                  expires_at: null
                  file_size: 277.5 KB
                  file_size_bytes: 284120
                  folder_id: 3
                  folder_name: Brand
                  id: 42
                  is_expired: false
                  is_primary_language: true
                  language_group_id: null
                  license_type: All rights reserved
                  mime_type: image/png
                  original_filename: spring-hero.png
                  permission: public
                  primary_language: en-US
                  rights_holder: Acme Inc.
                  tags:
                  - spring
                  - campaign
                  title: Spring hero banner
                  updated_at: '2026-07-17T12:05:00+00:00'
                  uploaded_by: Ada Lovelace
                  version: 1
                  version_count: 1
              schema:
                properties:
                  data:
                    properties:
                      ai_alt_text:
                        type: string
                      asset_type:
                        type: string
                      content_type:
                        type: string
                      created_at:
                        type: string
                      custom_metadata:
                        properties:
                          Campaign:
                            type: string
                        type: object
                      description:
                        type: string
                      download_url:
                        type: string
                      expires_at:
                        nullable: true
                      file_size:
                        type: string
                      file_size_bytes:
                        type: integer
                      folder_id:
                        type: integer
                      folder_name:
                        type: string
                      id:
                        type: integer
                      is_expired:
                        type: boolean
                      is_primary_language:
                        type: boolean
                      language_group_id:
                        nullable: true
                      license_type:
                        type: string
                      mime_type:
                        type: string
                      original_filename:
                        type: string
                      permission:
                        type: string
                      primary_language:
                        type: string
                      rights_holder:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                      uploaded_by:
                        type: string
                      version:
                        type: integer
                      version_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get full details for a single asset.
      tags:
      - Assets
    patch:
      description: 'Body (JSON), all optional: title, description, permission, folder_id,
        tags

        (array or comma string), content_type, rights_holder, license_type,

        expires_at (YYYY-MM-DD or null), primary_language.'
      parameters:
      - in: path
        name: asset_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              permission: public
              tags:
              - spring
              - hero
              title: Renamed banner
            schema:
              properties:
                permission:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_alt_text: A field of tulips at sunrise.
                  asset_type: image
                  content_type: Social
                  created_at: '2026-07-17T12:00:00+00:00'
                  custom_metadata:
                    Campaign: Spring 2026
                  description: Homepage hero for the spring campaign.
                  download_url: https://api.totalctrl.app/d/abc123def456
                  expires_at: null
                  file_size: 277.5 KB
                  file_size_bytes: 284120
                  folder_id: 3
                  folder_name: Brand
                  id: 42
                  is_expired: false
                  is_primary_language: true
                  language_group_id: null
                  license_type: All rights reserved
                  mime_type: image/png
                  original_filename: spring-hero.png
                  permission: public
                  primary_language: en-US
                  rights_holder: Acme Inc.
                  tags:
                  - spring
                  - campaign
                  title: Spring hero banner
                  updated_at: '2026-07-17T12:05:00+00:00'
                  uploaded_by: Ada Lovelace
                  version: 1
                  version_count: 1
              schema:
                properties:
                  data:
                    properties:
                      ai_alt_text:
                        type: string
                      asset_type:
                        type: string
                      content_type:
                        type: string
                      created_at:
                        type: string
                      custom_metadata:
                        properties:
                          Campaign:
                            type: string
                        type: object
                      description:
                        type: string
                      download_url:
                        type: string
                      expires_at:
                        nullable: true
                      file_size:
                        type: string
                      file_size_bytes:
                        type: integer
                      folder_id:
                        type: integer
                      folder_name:
                        type: string
                      id:
                        type: integer
                      is_expired:
                        type: boolean
                      is_primary_language:
                        type: boolean
                      language_group_id:
                        nullable: true
                      license_type:
                        type: string
                      mime_type:
                        type: string
                      original_filename:
                        type: string
                      permission:
                        type: string
                      primary_language:
                        type: string
                      rights_holder:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                      uploaded_by:
                        type: string
                      version:
                        type: integer
                      version_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update an asset's metadata.
      tags:
      - Assets
  /automations:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  automations:
                  - action_type: create_inbox_item
                    is_active: true
                    name: Escalate overdue tickets
                    run_count: 17
                    trigger_type: tc_event
                    uid: f9e8d7c6
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      automations:
                        items:
                          properties:
                            action_type:
                              type: string
                            is_active:
                              type: boolean
                            name:
                              type: string
                            run_count:
                              type: integer
                            trigger_type:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: GET /api/v1/automations
      tags:
      - Automations
    post:
      requestBody:
        content:
          application/json:
            example:
              action_config:
                priority: high
              action_type: create_inbox_item
              description: Create an inbox item when a ticket is overdue.
              name: Escalate overdue tickets
              requires_approval: true
              trigger_config:
                event: ticket.overdue
              trigger_type: tc_event
            schema:
              properties:
                action_config:
                  properties:
                    priority:
                      type: string
                  type: object
                action_type:
                  type: string
                description:
                  type: string
                name:
                  type: string
                requires_approval:
                  type: boolean
                trigger_config:
                  properties:
                    event:
                      type: string
                  type: object
                trigger_type:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  name: Escalate overdue tickets
                  uid: f9e8d7c6
              schema:
                properties:
                  data:
                    properties:
                      name:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: POST /api/v1/automations
      tags:
      - Automations
  /automations/{automation_uid}:
    delete:
      parameters:
      - in: path
        name: automation_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: DELETE /api/v1/automations/<uid>
      tags:
      - Automations
    get:
      parameters:
      - in: path
        name: automation_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  action_config:
                    priority: high
                  action_type: create_inbox_item
                  description: Create an inbox item when a ticket is overdue.
                  is_active: true
                  name: Escalate overdue tickets
                  recent_runs:
                  - created_at: '2026-07-17T14:00:00+00:00'
                    status: completed
                    uid: run_1a2b3c
                  requires_approval: true
                  run_count: 17
                  trigger_config:
                    event: ticket.overdue
                  trigger_type: tc_event
                  uid: f9e8d7c6
              schema:
                properties:
                  data:
                    properties:
                      action_config:
                        properties:
                          priority:
                            type: string
                        type: object
                      action_type:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      name:
                        type: string
                      recent_runs:
                        items:
                          properties:
                            created_at:
                              type: string
                            status:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      requires_approval:
                        type: boolean
                      run_count:
                        type: integer
                      trigger_config:
                        properties:
                          event:
                            type: string
                        type: object
                      trigger_type:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: GET /api/v1/automations/<uid>
      tags:
      - Automations
    patch:
      parameters:
      - in: path
        name: automation_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              is_active: false
              name: Escalate overdue tickets
            schema:
              properties:
                is_active:
                  type: boolean
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  uid: f9e8d7c6
                  updated: true
              schema:
                properties:
                  data:
                    properties:
                      uid:
                        type: string
                      updated:
                        type: boolean
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: PATCH /api/v1/automations/<uid>
      tags:
      - Automations
  /automations/{automation_uid}/run:
    post:
      parameters:
      - in: path
        name: automation_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              example:
                data:
                  queued: true
                  run_uid: run_1a2b3c
              schema:
                properties:
                  data:
                    properties:
                      queued:
                        type: boolean
                      run_uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Queue a manual run.
      tags:
      - Automations
  /block-templates:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  block_templates:
                  - blocks: 4
                    brand_kit: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                    id: e4d5c6b7-8a9f-4b1c-9d2e-3f4a5b6c7d8e
                    kind: email
                    name: Welcome email
                    updated_at: '2026-07-17T12:00:00+00:00'
                  count: 1
              schema:
                properties:
                  data:
                    properties:
                      block_templates:
                        items:
                          properties:
                            blocks:
                              type: integer
                            brand_kit:
                              type: string
                            id:
                              type: string
                            kind:
                              type: string
                            name:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List the tenant's block templates. Optional ?kind=email|section|page.
      tags:
      - Block Templates
  /block-templates/{bt_uuid}:
    get:
      parameters:
      - in: path
        name: bt_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  blocks: 4
                  blocks_list:
                  - id: blk_1
                    settings:
                      level: 1
                      text: Welcome
                    type: heading
                  brand_kit: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  id: e4d5c6b7-8a9f-4b1c-9d2e-3f4a5b6c7d8e
                  kind: email
                  name: Welcome email
                  updated_at: '2026-07-17T12:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      blocks:
                        type: integer
                      blocks_list:
                        items:
                          properties:
                            id:
                              type: string
                            settings:
                              properties:
                                level:
                                  type: integer
                                text:
                                  type: string
                              type: object
                            type:
                              type: string
                          type: object
                        type: array
                      brand_kit:
                        type: string
                      id:
                        type: string
                      kind:
                        type: string
                      name:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a block template, including its raw block list.
      tags:
      - Block Templates
  /block-templates/{bt_uuid}/render:
    get:
      parameters:
      - in: path
        name: bt_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  html: <table>...</table>
                  id: e4d5c6b7-8a9f-4b1c-9d2e-3f4a5b6c7d8e
                  medium: email
                  name: Welcome email
              schema:
                properties:
                  data:
                    properties:
                      html:
                        type: string
                      id:
                        type: string
                      medium:
                        type: string
                      name:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Render a block template to HTML. ?medium=email (default) | web.
      tags:
      - Block Templates
  /calendar/bookings:
    get:
      description: List calendar bookings for the tenant. Filter by `?status=confirmed|cancelled|no_show`
        and `?upcoming=true` (default) to return only future bookings.
      parameters:
      - in: query
        name: status
        schema:
          enum:
          - confirmed
          - cancelled
          - no_show
          - rescheduled
          type: string
      - description: If true, only return future bookings.
        in: query
        name: upcoming
        schema:
          default: true
          type: boolean
      - in: query
        name: limit
        schema:
          default: 25
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CalendarBooking'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List bookings
      tags:
      - Calendar
  /calendar/bookings/{booking_id}:
    get:
      description: Get full details for a single calendar booking by ID.
      parameters:
      - in: path
        name: booking_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CalendarBooking'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get booking
      tags:
      - Calendar
  /calendar/event-types:
    get:
      description: List all bookable event types (meeting templates) for the tenant.
        Filter with `?active_only=true` (default) to show only active types.
      parameters:
      - in: query
        name: active_only
        schema:
          default: true
          type: boolean
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CalendarEventType'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List event types
      tags:
      - Calendar
    post:
      description: Create a new bookable event type for the authenticated user. The
        event type will be immediately available for booking via its generated URL.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarEventTypeInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CalendarEventType'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create event type
      tags:
      - Calendar
  /ccms/publications:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  publications:
                  - conditions_applied:
                      audience:
                      - admin
                      platform:
                      - web
                    created_at: '2026-06-01T09:30:00'
                    custom_domain: docs.acme.com
                    custom_domain_verified: true
                    description: End-user documentation portal.
                    is_published: true
                    name: User Guide 2026
                    output_html_key: ccms/publications/c3d4/output.html
                    output_pdf_key: null
                    primary_color: '#1a56db'
                    pub_type: web_help
                    pub_type_label: Web Help
                    published_at: '2026-07-15T08:00:00'
                    slug: user-guide-2026
                    structure:
                      nodes:
                      - title: Getting Started
                        type: topic
                        uid: t1
                    topic_count: 24
                    uid: c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
                    updated_at: '2026-07-15T08:00:00'
                    variable_set: default
                    version_label: v3.2
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      publications:
                        items:
                          properties:
                            conditions_applied:
                              properties:
                                audience:
                                  items:
                                    type: string
                                  type: array
                                platform:
                                  items:
                                    type: string
                                  type: array
                              type: object
                            created_at:
                              type: string
                            custom_domain:
                              type: string
                            custom_domain_verified:
                              type: boolean
                            description:
                              type: string
                            is_published:
                              type: boolean
                            name:
                              type: string
                            output_html_key:
                              type: string
                            output_pdf_key:
                              nullable: true
                            primary_color:
                              type: string
                            pub_type:
                              type: string
                            pub_type_label:
                              type: string
                            published_at:
                              type: string
                            slug:
                              type: string
                            structure:
                              properties:
                                nodes:
                                  items:
                                    properties:
                                      title:
                                        type: string
                                      type:
                                        type: string
                                      uid:
                                        type: string
                                    type: object
                                  type: array
                              type: object
                            topic_count:
                              type: integer
                            uid:
                              type: string
                            updated_at:
                              type: string
                            variable_set:
                              type: string
                            version_label:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List publications.
      tags:
      - Content Components (CCMS)
  /ccms/publications/{pub_uid}:
    get:
      parameters:
      - in: path
        name: pub_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  conditions_applied:
                    audience:
                    - admin
                    platform:
                    - web
                  created_at: '2026-06-01T09:30:00'
                  custom_domain: docs.acme.com
                  custom_domain_verified: true
                  description: End-user documentation portal.
                  is_published: true
                  name: User Guide 2026
                  output_html_key: ccms/publications/c3d4/output.html
                  output_pdf_key: null
                  primary_color: '#1a56db'
                  pub_type: web_help
                  pub_type_label: Web Help
                  published_at: '2026-07-15T08:00:00'
                  slug: user-guide-2026
                  structure:
                    nodes:
                    - title: Getting Started
                      type: topic
                      uid: t1
                  topic_count: 24
                  uid: c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
                  updated_at: '2026-07-15T08:00:00'
                  variable_set: default
                  version_label: v3.2
              schema:
                properties:
                  data:
                    properties:
                      conditions_applied:
                        properties:
                          audience:
                            items:
                              type: string
                            type: array
                          platform:
                            items:
                              type: string
                            type: array
                        type: object
                      created_at:
                        type: string
                      custom_domain:
                        type: string
                      custom_domain_verified:
                        type: boolean
                      description:
                        type: string
                      is_published:
                        type: boolean
                      name:
                        type: string
                      output_html_key:
                        type: string
                      output_pdf_key:
                        nullable: true
                      primary_color:
                        type: string
                      pub_type:
                        type: string
                      pub_type_label:
                        type: string
                      published_at:
                        type: string
                      slug:
                        type: string
                      structure:
                        properties:
                          nodes:
                            items:
                              properties:
                                title:
                                  type: string
                                type:
                                  type: string
                                uid:
                                  type: string
                              type: object
                            type: array
                        type: object
                      topic_count:
                        type: integer
                      uid:
                        type: string
                      updated_at:
                        type: string
                      variable_set:
                        type: string
                      version_label:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a publication.
      tags:
      - Content Components (CCMS)
  /ccms/publications/{pub_uid}/jobs:
    get:
      parameters:
      - in: path
        name: pub_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  jobs:
                  - created_at: '2026-07-15T07:58:30'
                    error_message: null
                    finished_at: '2026-07-15T08:00:00'
                    job_type: full
                    log: Rendered 24 topics; generated HTML + PDF.
                    started_at: '2026-07-15T07:59:00'
                    status: done
                    status_color: success
                    uid: d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f90
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      jobs:
                        items:
                          properties:
                            created_at:
                              type: string
                            error_message:
                              nullable: true
                            finished_at:
                              type: string
                            job_type:
                              type: string
                            log:
                              type: string
                            started_at:
                              type: string
                            status:
                              type: string
                            status_color:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List publish jobs.
      tags:
      - Content Components (CCMS)
  /ccms/snippets:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  snippets:
                  - content_html: <p>All rights reserved. (c) ACME Corp.</p>
                    created_at: '2026-07-01T09:30:00'
                    description: Standard legal footer for release notes.
                    is_active: true
                    language: en
                    name: Legal Disclaimer
                    tags:
                    - legal
                    - footer
                    uid: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    updated_at: '2026-07-10T14:05:00'
                    usage_count: 12
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      snippets:
                        items:
                          properties:
                            content_html:
                              type: string
                            created_at:
                              type: string
                            description:
                              type: string
                            is_active:
                              type: boolean
                            language:
                              type: string
                            name:
                              type: string
                            tags:
                              items:
                                type: string
                              type: array
                            uid:
                              type: string
                            updated_at:
                              type: string
                            usage_count:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List active snippets (?q, ?language).
      tags:
      - Content Components (CCMS)
    post:
      requestBody:
        content:
          application/json:
            example:
              content_html: <p>All rights reserved. (c) ACME Corp.</p>
              description: Standard legal footer for release notes.
              language: en
              name: Legal Disclaimer
              tags:
              - legal
              - footer
            schema:
              properties:
                content_html:
                  type: string
                description:
                  type: string
                language:
                  type: string
                name:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  content_html: <p>All rights reserved. (c) ACME Corp.</p>
                  created_at: '2026-07-01T09:30:00'
                  description: Standard legal footer for release notes.
                  is_active: true
                  language: en
                  name: Legal Disclaimer
                  tags:
                  - legal
                  - footer
                  uid: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                  updated_at: '2026-07-10T14:05:00'
                  usage_count: 12
              schema:
                properties:
                  data:
                    properties:
                      content_html:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      language:
                        type: string
                      name:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                      usage_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a snippet.
      tags:
      - Content Components (CCMS)
  /ccms/snippets/{snippet_uid}:
    delete:
      parameters:
      - in: path
        name: snippet_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a snippet.
      tags:
      - Content Components (CCMS)
    get:
      parameters:
      - in: path
        name: snippet_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  content_html: <p>All rights reserved. (c) ACME Corp.</p>
                  created_at: '2026-07-01T09:30:00'
                  description: Standard legal footer for release notes.
                  is_active: true
                  language: en
                  name: Legal Disclaimer
                  tags:
                  - legal
                  - footer
                  uid: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                  updated_at: '2026-07-10T14:05:00'
                  usage_count: 12
              schema:
                properties:
                  data:
                    properties:
                      content_html:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      language:
                        type: string
                      name:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                      usage_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get snippet with content.
      tags:
      - Content Components (CCMS)
    patch:
      parameters:
      - in: path
        name: snippet_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content_html: <p>All rights reserved.</p>
              description: Updated footer.
              is_active: true
              language: en
              name: Legal Disclaimer
              tags:
              - legal
            schema:
              properties:
                content_html:
                  type: string
                description:
                  type: string
                is_active:
                  type: boolean
                language:
                  type: string
                name:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  content_html: <p>All rights reserved. (c) ACME Corp.</p>
                  created_at: '2026-07-01T09:30:00'
                  description: Standard legal footer for release notes.
                  is_active: true
                  language: en
                  name: Legal Disclaimer
                  tags:
                  - legal
                  - footer
                  uid: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                  updated_at: '2026-07-10T14:05:00'
                  usage_count: 12
              schema:
                properties:
                  data:
                    properties:
                      content_html:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      language:
                        type: string
                      name:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                      usage_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a snippet.
      tags:
      - Content Components (CCMS)
  /ccms/topics:
    get:
      description: "Query params (all optional):\n  topic_type, status, language,\
        \ limit (default 50), offset (default 0)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  limit: 50
                  offset: 0
                  topics:
                  - conditions: []
                    created_at: '2026-07-17T12:00:00'
                    domain: support
                    language: en
                    slug: how-to-reset-your-password
                    source_topic_id: null
                    status: draft
                    status_color: secondary
                    summary: Steps to reset an account password.
                    tags:
                    - account
                    - security
                    title: How to reset your password
                    topic_type: task
                    type_icon: list-check
                    type_label: Task
                    uid: b8c9d0e1-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    word_count: 8
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      topics:
                        items:
                          properties:
                            conditions:
                              items: {}
                              type: array
                            created_at:
                              type: string
                            domain:
                              type: string
                            language:
                              type: string
                            slug:
                              type: string
                            source_topic_id:
                              nullable: true
                            status:
                              type: string
                            status_color:
                              type: string
                            summary:
                              type: string
                            tags:
                              items:
                                type: string
                              type: array
                            title:
                              type: string
                            topic_type:
                              type: string
                            type_icon:
                              type: string
                            type_label:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                            word_count:
                              type: integer
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List topics.
      tags:
      - Content Components (CCMS)
    post:
      description: "Body JSON (required: title, topic_type):\n  title, topic_type,\
        \ content_html, summary, language, domain, tags"
      requestBody:
        content:
          application/json:
            example:
              content_html: <p>Open Settings and click Reset password.</p>
              domain: support
              language: en
              summary: Steps to reset an account password.
              tags:
              - account
              - security
              title: How to reset your password
              topic_type: task
            schema:
              properties:
                content_html:
                  type: string
                domain:
                  type: string
                language:
                  type: string
                summary:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
                topic_type:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  conditions: []
                  content_html: <p>Open Settings and click Reset password.</p>
                  created_at: '2026-07-17T12:00:00'
                  domain: support
                  language: en
                  slug: how-to-reset-your-password
                  source_topic_id: null
                  status: draft
                  status_color: secondary
                  summary: Steps to reset an account password.
                  tags:
                  - account
                  - security
                  title: How to reset your password
                  topic_type: task
                  type_icon: list-check
                  type_label: Task
                  uid: b8c9d0e1-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  word_count: 8
              schema:
                properties:
                  data:
                    properties:
                      conditions:
                        items: {}
                        type: array
                      content_html:
                        type: string
                      created_at:
                        type: string
                      domain:
                        type: string
                      language:
                        type: string
                      slug:
                        type: string
                      source_topic_id:
                        nullable: true
                      status:
                        type: string
                      status_color:
                        type: string
                      summary:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      topic_type:
                        type: string
                      type_icon:
                        type: string
                      type_label:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a topic.
      tags:
      - Content Components (CCMS)
  /ccms/topics/search:
    get:
      description: "Query params:\n  q (required), topic_type (optional), limit (default\
        \ 10)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  query: password
                  topics:
                  - conditions: []
                    created_at: '2026-07-17T12:00:00'
                    domain: support
                    language: en
                    slug: how-to-reset-your-password
                    source_topic_id: null
                    status: draft
                    status_color: secondary
                    summary: Steps to reset an account password.
                    tags:
                    - account
                    - security
                    title: How to reset your password
                    topic_type: task
                    type_icon: list-check
                    type_label: Task
                    uid: b8c9d0e1-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    word_count: 8
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      query:
                        type: string
                      topics:
                        items:
                          properties:
                            conditions:
                              items: {}
                              type: array
                            created_at:
                              type: string
                            domain:
                              type: string
                            language:
                              type: string
                            slug:
                              type: string
                            source_topic_id:
                              nullable: true
                            status:
                              type: string
                            status_color:
                              type: string
                            summary:
                              type: string
                            tags:
                              items:
                                type: string
                              type: array
                            title:
                              type: string
                            topic_type:
                              type: string
                            type_icon:
                              type: string
                            type_label:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                            word_count:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Search topics by title/summary.
      tags:
      - Content Components (CCMS)
  /ccms/topics/{topic_uid}:
    delete:
      parameters:
      - in: path
        name: topic_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a topic.
      tags:
      - Content Components (CCMS)
    get:
      parameters:
      - in: path
        name: topic_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  conditions: []
                  content_html: <p>Open Settings and click Reset password.</p>
                  created_at: '2026-07-17T12:00:00'
                  domain: support
                  language: en
                  slug: how-to-reset-your-password
                  source_topic_id: null
                  status: draft
                  status_color: secondary
                  summary: Steps to reset an account password.
                  tags:
                  - account
                  - security
                  title: How to reset your password
                  topic_type: task
                  type_icon: list-check
                  type_label: Task
                  uid: b8c9d0e1-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  word_count: 8
              schema:
                properties:
                  data:
                    properties:
                      conditions:
                        items: {}
                        type: array
                      content_html:
                        type: string
                      created_at:
                        type: string
                      domain:
                        type: string
                      language:
                        type: string
                      slug:
                        type: string
                      source_topic_id:
                        nullable: true
                      status:
                        type: string
                      status_color:
                        type: string
                      summary:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      topic_type:
                        type: string
                      type_icon:
                        type: string
                      type_label:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get topic with content.
      tags:
      - Content Components (CCMS)
    patch:
      parameters:
      - in: path
        name: topic_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content_html: <p>Updated steps.</p>
              status: published
              summary: Updated summary.
              tags:
              - account
              title: How to reset your password
            schema:
              properties:
                content_html:
                  type: string
                status:
                  type: string
                summary:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  conditions: []
                  content_html: <p>Open Settings and click Reset password.</p>
                  created_at: '2026-07-17T12:00:00'
                  domain: support
                  language: en
                  slug: how-to-reset-your-password
                  source_topic_id: null
                  status: draft
                  status_color: secondary
                  summary: Steps to reset an account password.
                  tags:
                  - account
                  - security
                  title: How to reset your password
                  topic_type: task
                  type_icon: list-check
                  type_label: Task
                  uid: b8c9d0e1-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  word_count: 8
              schema:
                properties:
                  data:
                    properties:
                      conditions:
                        items: {}
                        type: array
                      content_html:
                        type: string
                      created_at:
                        type: string
                      domain:
                        type: string
                      language:
                        type: string
                      slug:
                        type: string
                      source_topic_id:
                        nullable: true
                      status:
                        type: string
                      status_color:
                        type: string
                      summary:
                        type: string
                      tags:
                        items:
                          type: string
                        type: array
                      title:
                        type: string
                      topic_type:
                        type: string
                      type_icon:
                        type: string
                      type_label:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a topic.
      tags:
      - Content Components (CCMS)
  /ccms/variables:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  variables:
                  - created_at: '2026-07-01T09:30:00'
                    default_value: TotalCtrl
                    description: Marketing name of the product.
                    is_active: true
                    key: product_name
                    label: Product Name
                    uid: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                    value_map:
                      default: TotalCtrl
                      eu: TotalCtrl EU
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      variables:
                        items:
                          properties:
                            created_at:
                              type: string
                            default_value:
                              type: string
                            description:
                              type: string
                            is_active:
                              type: boolean
                            key:
                              type: string
                            label:
                              type: string
                            uid:
                              type: string
                            value_map:
                              properties:
                                default:
                                  type: string
                                eu:
                                  type: string
                              type: object
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List active variables.
      tags:
      - Content Components (CCMS)
    post:
      requestBody:
        content:
          application/json:
            example:
              description: Marketing name of the product.
              key: product_name
              label: Product Name
              value_map:
                default: TotalCtrl
            schema:
              properties:
                description:
                  type: string
                key:
                  type: string
                label:
                  type: string
                value_map:
                  properties:
                    default:
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:30:00'
                  default_value: TotalCtrl
                  description: Marketing name of the product.
                  is_active: true
                  key: product_name
                  label: Product Name
                  uid: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                  value_map:
                    default: TotalCtrl
                    eu: TotalCtrl EU
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      default_value:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      key:
                        type: string
                      label:
                        type: string
                      uid:
                        type: string
                      value_map:
                        properties:
                          default:
                            type: string
                          eu:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a variable.
      tags:
      - Content Components (CCMS)
  /ccms/variables/{var_uid}:
    get:
      parameters:
      - in: path
        name: var_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:30:00'
                  default_value: TotalCtrl
                  description: Marketing name of the product.
                  is_active: true
                  key: product_name
                  label: Product Name
                  uid: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                  value_map:
                    default: TotalCtrl
                    eu: TotalCtrl EU
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      default_value:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      key:
                        type: string
                      label:
                        type: string
                      uid:
                        type: string
                      value_map:
                        properties:
                          default:
                            type: string
                          eu:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a variable.
      tags:
      - Content Components (CCMS)
    patch:
      parameters:
      - in: path
        name: var_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: Marketing name of the product.
              is_active: true
              key: product_name
              label: Product Name
              value_map:
                default: TotalCtrl
                eu: TotalCtrl EU
            schema:
              properties:
                description:
                  type: string
                is_active:
                  type: boolean
                key:
                  type: string
                label:
                  type: string
                value_map:
                  properties:
                    default:
                      type: string
                    eu:
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:30:00'
                  default_value: TotalCtrl
                  description: Marketing name of the product.
                  is_active: true
                  key: product_name
                  label: Product Name
                  uid: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                  value_map:
                    default: TotalCtrl
                    eu: TotalCtrl EU
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      default_value:
                        type: string
                      description:
                        type: string
                      is_active:
                        type: boolean
                      key:
                        type: string
                      label:
                        type: string
                      uid:
                        type: string
                      value_map:
                        properties:
                          default:
                            type: string
                          eu:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a variable.
      tags:
      - Content Components (CCMS)
  /community:
    get:
      description: Returns all communities for this account.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Community'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List communities
      tags:
      - Community
  /community/{community_id}/members:
    get:
      description: Returns active members of a community, most recently joined first.
      parameters:
      - in: path
        name: community_id
        required: true
        schema:
          type: integer
      - in: query
        name: limit
        schema:
          default: 50
          maximum: 200
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CommunityMember'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List members
      tags:
      - Community
  /community/{community_id}/posts:
    get:
      description: Returns paginated posts in a community. Optionally filter by `?space_id=N`
        to scope to a specific channel/space.
      parameters:
      - in: path
        name: community_id
        required: true
        schema:
          type: integer
      - description: Filter to a specific space/channel.
        in: query
        name: space_id
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CommunityPost'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List posts
      tags:
      - Community
    post:
      description: 'Create a new post in a community. The post is attributed to the
        authenticated user.


        **Webhook event fired:** `community.post.created`'
      parameters:
      - in: path
        name: community_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommunityPostInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CommunityPost'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create post
      tags:
      - Community
  /contacts:
    get:
      description: 'Returns a de-duplicated list of contacts aggregated from all source
        apps (CRM, Accounting, Community). Contacts with the same email address are
        merged into a single record tagged with source badges.


        Filter by `?source=crm|accounting|community` or search by name/email with
        `?q=`.'
      parameters:
      - description: Search term (name or email).
        in: query
        name: q
        schema:
          type: string
      - description: Filter to one source app.
        in: query
        name: source
        schema:
          enum:
          - ''
          - crm
          - accounting
          - community
          type: string
      - in: query
        name: sort
        schema:
          default: name
          enum:
          - name
          - newest
          - oldest
          type: string
      - in: query
        name: limit
        schema:
          default: 25
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/UnifiedContact'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List contacts
      tags:
      - Unified Contacts
    post:
      description: 'Create a new unified contact. The contact is stored as a CRM contact
        and will appear in the unified Contacts view.


        **Webhook event fired:** `contacts.created`'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedContactInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedContact'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create contact
      tags:
      - Unified Contacts
  /contacts/{contact_id}:
    delete:
      description: 'Permanently delete a unified contact. This removes the underlying
        CRM contact record.


        **Webhook event fired:** `contacts.deleted`'
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete contact
      tags:
      - Unified Contacts
    get:
      description: Get a unified contact by CRM contact ID.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedContact'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get contact
      tags:
      - Unified Contacts
    patch:
      description: 'Update a unified contact. Pass only the fields you wish to change.


        **Webhook event fired:** `contacts.updated`'
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedContactInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedContact'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update contact
      tags:
      - Unified Contacts
  /creator/assets:
    get:
      description: 'List content assets for the account.


        Filter by `status` (draft, ready, published), `asset_type`, or `campaign_id`.
        Results are ordered by most recently updated first.


        **Webhook events:** `creator.asset.created`, `creator.asset.generated`'
      parameters:
      - in: query
        name: status
        schema:
          enum:
          - draft
          - generating
          - ready
          - published
          type: string
      - in: query
        name: asset_type
        schema:
          type: string
      - in: query
        name: campaign_id
        schema:
          format: uuid
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CreatorAsset'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List assets
      tags:
      - Creator
    post:
      description: 'Create a new content asset. Set `generate: true` (default) to
        trigger AI content generation immediately after creation.


        **Webhook events:** `creator.asset.created`, `creator.asset.generated`'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorAssetInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CreatorAsset'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create asset
      tags:
      - Creator
  /creator/assets/{asset_uuid}:
    delete:
      description: 'Returns 200 {deleted: true}'
      parameters:
      - in: path
        name: asset_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Archive (soft-delete) a content asset.
      tags:
      - Creator
    get:
      description: 'Returns 200 {asset: {...}} with content_html included.'
      parameters:
      - in: path
        name: asset_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  asset:
                    asset_type: blog_post
                    audience: SMB decision-makers
                    brief: Write a launch announcement.
                    campaign_id: null
                    content_html: <h1>Announcing our new feature</h1><p>Today we are
                      excited...</p>
                    created_at: '2026-02-04T12:00:00+00:00'
                    id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    plain_text_preview: Today we are excited to announce...
                    status: ready
                    title: Announcing our new feature
                    tone: professional
                    updated_at: '2026-02-04T12:01:30+00:00'
                    version: 1
                    word_count: 520
              schema:
                properties:
                  data:
                    properties:
                      asset:
                        properties:
                          asset_type:
                            type: string
                          audience:
                            type: string
                          brief:
                            type: string
                          campaign_id:
                            nullable: true
                          content_html:
                            type: string
                          created_at:
                            type: string
                          id:
                            type: string
                          plain_text_preview:
                            type: string
                          status:
                            type: string
                          title:
                            type: string
                          tone:
                            type: string
                          updated_at:
                            type: string
                          version:
                            type: integer
                          word_count:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single content asset by UUID.
      tags:
      - Creator
    patch:
      description: "Body (JSON — all optional):\n  title, brief, tone, audience, status,\
        \ content_html\n\nReturns 200 {asset: {...}}"
      parameters:
      - in: path
        name: asset_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              audience: SMB decision-makers
              brief: Write a launch announcement.
              content_html: <h1>Announcing our new feature</h1><p>Today we are excited...</p>
              status: ready
              title: Announcing our new feature
              tone: professional
            schema:
              properties:
                audience:
                  type: string
                brief:
                  type: string
                content_html:
                  type: string
                status:
                  type: string
                title:
                  type: string
                tone:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  asset:
                    asset_type: blog_post
                    audience: SMB decision-makers
                    brief: Write a launch announcement.
                    campaign_id: null
                    created_at: '2026-02-04T12:00:00+00:00'
                    id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    plain_text_preview: Today we are excited to announce...
                    status: ready
                    title: Announcing our new feature
                    tone: professional
                    updated_at: '2026-02-04T12:01:30+00:00'
                    version: 1
                    word_count: 520
              schema:
                properties:
                  data:
                    properties:
                      asset:
                        properties:
                          asset_type:
                            type: string
                          audience:
                            type: string
                          brief:
                            type: string
                          campaign_id:
                            nullable: true
                          created_at:
                            type: string
                          id:
                            type: string
                          plain_text_preview:
                            type: string
                          status:
                            type: string
                          title:
                            type: string
                          tone:
                            type: string
                          updated_at:
                            type: string
                          version:
                            type: integer
                          word_count:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a content asset's fields.
      tags:
      - Creator
    put:
      description: "Body (JSON — all optional):\n  title, brief, tone, audience, status,\
        \ content_html\n\nReturns 200 {asset: {...}}"
      parameters:
      - in: path
        name: asset_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              audience: SMB decision-makers
              brief: Write a launch announcement.
              content_html: <h1>Announcing our new feature</h1><p>Today we are excited...</p>
              status: ready
              title: Announcing our new feature
              tone: professional
            schema:
              properties:
                audience:
                  type: string
                brief:
                  type: string
                content_html:
                  type: string
                status:
                  type: string
                title:
                  type: string
                tone:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  asset:
                    asset_type: blog_post
                    audience: SMB decision-makers
                    brief: Write a launch announcement.
                    campaign_id: null
                    created_at: '2026-02-04T12:00:00+00:00'
                    id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    plain_text_preview: Today we are excited to announce...
                    status: ready
                    title: Announcing our new feature
                    tone: professional
                    updated_at: '2026-02-04T12:01:30+00:00'
                    version: 1
                    word_count: 520
              schema:
                properties:
                  data:
                    properties:
                      asset:
                        properties:
                          asset_type:
                            type: string
                          audience:
                            type: string
                          brief:
                            type: string
                          campaign_id:
                            nullable: true
                          created_at:
                            type: string
                          id:
                            type: string
                          plain_text_preview:
                            type: string
                          status:
                            type: string
                          title:
                            type: string
                          tone:
                            type: string
                          updated_at:
                            type: string
                          version:
                            type: integer
                          word_count:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a content asset's fields.
      tags:
      - Creator
  /creator/assets/{asset_uuid}/schedule:
    post:
      description: "Body (JSON):\n  schedule_type    — \"one_time\" | \"recurring\"\
        \  (required)\n  run_at           — ISO 8601 datetime, required for one_time\n\
        \  recur_days       — list of day names, required for recurring\n        \
        \             e.g. [\"monday\", \"wednesday\", \"friday\"]\n  recur_time \
        \      — \"HH:MM\" UTC, required for recurring\n  recur_end_date   — \"YYYY-MM-DD\"\
        \ or null\n  content_mode     — \"current\" | \"regenerate\" (default: \"\
        current\")\n  regen_brief      — str, optional (used when content_mode = regenerate)\n\
        \  regen_continuity — bool (default false)\n  regen_extra_instr— str, optional\n\
        \  destinations     — list of destination keys (required, ≥ 1)\n         \
        \            e.g. [\"twitter_x\", \"assets\", \"website\"]\n  dest_options\
        \     — dict of per-destination options (optional)\n\nReturns 201 {schedule:\
        \ {...}}"
      parameters:
      - in: path
        name: asset_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content_mode: current
              dest_options: {}
              destinations:
              - twitter_x
              - website
              recur_days:
              - monday
              - wednesday
              - friday
              recur_end_date: null
              recur_time: 09:00
              regen_brief: null
              regen_continuity: false
              regen_extra_instr: null
              schedule_type: recurring
            schema:
              properties:
                content_mode:
                  type: string
                dest_options:
                  properties: {}
                  type: object
                destinations:
                  items:
                    type: string
                  type: array
                recur_days:
                  items:
                    type: string
                  type: array
                recur_end_date:
                  nullable: true
                recur_time:
                  type: string
                regen_brief:
                  nullable: true
                regen_continuity:
                  type: boolean
                regen_extra_instr:
                  nullable: true
                schedule_type:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  schedule:
                    asset_id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    asset_title: Announcing our new feature
                    content_mode: current
                    created_at: '2026-02-04T12:05:00+00:00'
                    dest_options: {}
                    destinations:
                    - twitter_x
                    - website
                    id: a7b8c9d0-e1f2-4a3b-4c5d-6e7f80911223
                    last_run_at: null
                    last_run_status: null
                    next_run_at: '2026-02-09T09:00:00+00:00'
                    recur_days:
                    - monday
                    - wednesday
                    - friday
                    recur_end_date: '2026-12-31'
                    recur_time: 09:00
                    regen_brief: null
                    regen_continuity: false
                    regen_extra_instr: null
                    run_at: null
                    run_count: 0
                    schedule_type: recurring
                    status: active
              schema:
                properties:
                  data:
                    properties:
                      schedule:
                        properties:
                          asset_id:
                            type: string
                          asset_title:
                            type: string
                          content_mode:
                            type: string
                          created_at:
                            type: string
                          dest_options:
                            properties: {}
                            type: object
                          destinations:
                            items:
                              type: string
                            type: array
                          id:
                            type: string
                          last_run_at:
                            nullable: true
                          last_run_status:
                            nullable: true
                          next_run_at:
                            type: string
                          recur_days:
                            items:
                              type: string
                            type: array
                          recur_end_date:
                            type: string
                          recur_time:
                            type: string
                          regen_brief:
                            nullable: true
                          regen_continuity:
                            type: boolean
                          regen_extra_instr:
                            nullable: true
                          run_at:
                            nullable: true
                          run_count:
                            type: integer
                          schedule_type:
                            type: string
                          status:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create (or replace) a delivery schedule for an asset.
      tags:
      - Creator
  /creator/campaigns:
    get:
      description: List content campaigns. Excludes archived campaigns by default.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CreatorCampaign'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List campaigns
      tags:
      - Creator
    post:
      description: 'Create a new content campaign.


        **Webhook events:** `creator.campaign.created`'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorCampaignInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CreatorCampaign'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create campaign
      tags:
      - Creator
  /creator/campaigns/{campaign_uuid}:
    get:
      description: 'Returns 200 {campaign: {...}, assets: [...]}'
      parameters:
      - in: path
        name: campaign_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assets:
                  - asset_type: blog_post
                    audience: SMB decision-makers
                    brief: Write a launch announcement.
                    campaign_id: null
                    created_at: '2026-02-04T12:00:00+00:00'
                    id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    plain_text_preview: Today we are excited to announce...
                    status: ready
                    title: Announcing our new feature
                    tone: professional
                    updated_at: '2026-02-04T12:01:30+00:00'
                    version: 1
                    word_count: 520
                  campaign:
                    asset_count: 5
                    brief: Spring product launch campaign.
                    created_at: '2026-02-04T09:00:00+00:00'
                    id: f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f809112
                    name: Q1 Launch
                    status: active
                    updated_at: '2026-02-04T12:01:30+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assets:
                        items:
                          properties:
                            asset_type:
                              type: string
                            audience:
                              type: string
                            brief:
                              type: string
                            campaign_id:
                              nullable: true
                            created_at:
                              type: string
                            id:
                              type: string
                            plain_text_preview:
                              type: string
                            status:
                              type: string
                            title:
                              type: string
                            tone:
                              type: string
                            updated_at:
                              type: string
                            version:
                              type: integer
                            word_count:
                              type: integer
                          type: object
                        type: array
                      campaign:
                        properties:
                          asset_count:
                            type: integer
                          brief:
                            type: string
                          created_at:
                            type: string
                          id:
                            type: string
                          name:
                            type: string
                          status:
                            type: string
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single creator campaign by UUID, including its asset list.
      tags:
      - Creator
  /creator/schedules:
    get:
      description: 'List content delivery schedules for the account.


        By default returns all non-cancelled schedules. Filter by `status` (active,
        paused, cancelled, completed) or `asset_id`.'
      parameters:
      - in: query
        name: status
        schema:
          enum:
          - active
          - paused
          - cancelled
          - completed
          type: string
      - in: query
        name: asset_id
        schema:
          format: uuid
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CreatorSchedule'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List schedules
      tags:
      - Creator
  /creator/schedules/{schedule_uuid}:
    delete:
      description: 'Returns 200 {schedule: {...}}'
      parameters:
      - in: path
        name: schedule_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  schedule:
                    asset_id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    asset_title: Announcing our new feature
                    content_mode: current
                    created_at: '2026-02-04T12:05:00+00:00'
                    dest_options: {}
                    destinations:
                    - twitter_x
                    - website
                    id: a7b8c9d0-e1f2-4a3b-4c5d-6e7f80911223
                    last_run_at: null
                    last_run_status: null
                    next_run_at: '2026-02-09T09:00:00+00:00'
                    recur_days:
                    - monday
                    - wednesday
                    - friday
                    recur_end_date: '2026-12-31'
                    recur_time: 09:00
                    regen_brief: null
                    regen_continuity: false
                    regen_extra_instr: null
                    run_at: null
                    run_count: 0
                    schedule_type: recurring
                    status: active
              schema:
                properties:
                  data:
                    properties:
                      schedule:
                        properties:
                          asset_id:
                            type: string
                          asset_title:
                            type: string
                          content_mode:
                            type: string
                          created_at:
                            type: string
                          dest_options:
                            properties: {}
                            type: object
                          destinations:
                            items:
                              type: string
                            type: array
                          id:
                            type: string
                          last_run_at:
                            nullable: true
                          last_run_status:
                            nullable: true
                          next_run_at:
                            type: string
                          recur_days:
                            items:
                              type: string
                            type: array
                          recur_end_date:
                            type: string
                          recur_time:
                            type: string
                          regen_brief:
                            nullable: true
                          regen_continuity:
                            type: boolean
                          regen_extra_instr:
                            nullable: true
                          run_at:
                            nullable: true
                          run_count:
                            type: integer
                          schedule_type:
                            type: string
                          status:
                            type: string
                        type: object
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Cancel a delivery schedule.
      tags:
      - Creator
    get:
      description: "Query params:\n  runs_limit — number of recent runs to include\
        \ (default 10, max 50)\n\nReturns 200 {schedule: {...}, runs: [...]}"
      parameters:
      - in: path
        name: schedule_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  runs:
                  - completed_at: '2026-02-09T09:00:12+00:00'
                    destinations_log: {}
                    error_msg: null
                    generated_title: Announcing our new feature
                    id: b8c9d0e1-f2a3-4b4c-5d6e-7f8091122334
                    run_at: '2026-02-09T09:00:00+00:00'
                    status: completed
                  schedule:
                    asset_id: e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091
                    asset_title: Announcing our new feature
                    content_mode: current
                    created_at: '2026-02-04T12:05:00+00:00'
                    dest_options: {}
                    destinations:
                    - twitter_x
                    - website
                    id: a7b8c9d0-e1f2-4a3b-4c5d-6e7f80911223
                    last_run_at: null
                    last_run_status: null
                    next_run_at: '2026-02-09T09:00:00+00:00'
                    recur_days:
                    - monday
                    - wednesday
                    - friday
                    recur_end_date: '2026-12-31'
                    recur_time: 09:00
                    regen_brief: null
                    regen_continuity: false
                    regen_extra_instr: null
                    run_at: null
                    run_count: 0
                    schedule_type: recurring
                    status: active
              schema:
                properties:
                  data:
                    properties:
                      runs:
                        items:
                          properties:
                            completed_at:
                              type: string
                            destinations_log:
                              properties: {}
                              type: object
                            error_msg:
                              nullable: true
                            generated_title:
                              type: string
                            id:
                              type: string
                            run_at:
                              type: string
                            status:
                              type: string
                          type: object
                        type: array
                      schedule:
                        properties:
                          asset_id:
                            type: string
                          asset_title:
                            type: string
                          content_mode:
                            type: string
                          created_at:
                            type: string
                          dest_options:
                            properties: {}
                            type: object
                          destinations:
                            items:
                              type: string
                            type: array
                          id:
                            type: string
                          last_run_at:
                            nullable: true
                          last_run_status:
                            nullable: true
                          next_run_at:
                            type: string
                          recur_days:
                            items:
                              type: string
                            type: array
                          recur_end_date:
                            type: string
                          recur_time:
                            type: string
                          regen_brief:
                            nullable: true
                          regen_continuity:
                            type: boolean
                          regen_extra_instr:
                            nullable: true
                          run_at:
                            nullable: true
                          run_count:
                            type: integer
                          schedule_type:
                            type: string
                          status:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single delivery schedule including recent run history.
      tags:
      - Creator
  /creator/schedules/{schedule_uuid}/run:
    post:
      description: 'Returns 202 {run: {...}}'
      parameters:
      - in: path
        name: schedule_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              example:
                data:
                  run:
                    completed_at: '2026-02-09T09:00:12+00:00'
                    destinations_log: {}
                    error_msg: null
                    generated_title: Announcing our new feature
                    id: b8c9d0e1-f2a3-4b4c-5d6e-7f8091122334
                    run_at: '2026-02-09T09:00:00+00:00'
                    status: completed
              schema:
                properties:
                  data:
                    properties:
                      run:
                        properties:
                          completed_at:
                            type: string
                          destinations_log:
                            properties: {}
                            type: object
                          error_msg:
                            nullable: true
                          generated_title:
                            type: string
                          id:
                            type: string
                          run_at:
                            type: string
                          status:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trigger an immediate run of a delivery schedule.
      tags:
      - Creator
  /crm/activities:
    get:
      description: 'Returns paginated activity log across all CRM records.


        Filter: `?contact_id=N`, `?company_id=N`, `?deal_id=N`, `?activity_type=call`'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: contact_id
        schema:
          type: integer
      - in: query
        name: company_id
        schema:
          type: integer
      - in: query
        name: deal_id
        schema:
          type: integer
      - in: query
        name: activity_type
        schema:
          enum:
          - call
          - email_sent
          - meeting
          - linkedin
          - demo
          - other
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmActivity'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List activities
      tags:
      - CRM
    post:
      description: Log a new CRM activity.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmActivityInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmActivity'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Log activity
      tags:
      - CRM
  /crm/activities/{act_id}:
    delete:
      parameters:
      - in: path
        name: act_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  activity_id: 1
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      activity_id:
                        type: integer
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an activity.
      tags:
      - CRM
  /crm/campaigns:
    get:
      description: 'Returns paginated campaigns. Filter: `?status=draft|sent|scheduled`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - scheduled
          - sending
          - sent
          - cancelled
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmCampaign'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List campaigns
      tags:
      - CRM
    post:
      description: Create a campaign in draft status.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmCampaignInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCampaign'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create campaign
      tags:
      - CRM
  /crm/campaigns/{campaign_id}:
    delete:
      description: Delete a campaign.
      parameters:
      - in: path
        name: campaign_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete campaign
      tags:
      - CRM
    get:
      description: Get a single campaign with stats.
      parameters:
      - in: path
        name: campaign_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCampaign'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get campaign
      tags:
      - CRM
    patch:
      description: Update a draft or scheduled campaign.
      parameters:
      - in: path
        name: campaign_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmCampaignInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCampaign'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update campaign
      tags:
      - CRM
  /crm/campaigns/{campaign_id}/send:
    post:
      description: 'Trigger campaign send to all subscribed members of the assigned
        list.


        Creates recipient records, sets `status=sent`, and fires the `crm.campaign.sent`
        webhook.


        **Webhook events fired:** `crm.campaign.sent`'
      parameters:
      - in: path
        name: campaign_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCampaign'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Send campaign
      tags:
      - CRM
  /crm/companies:
    get:
      description: 'Returns paginated companies. Filter: `?q=name_or_domain`, `?industry=SaaS`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: q
        schema:
          type: string
      - in: query
        name: industry
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmCompany'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List companies
      tags:
      - CRM
    post:
      description: Create a new company record.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmCompanyInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCompany'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create company
      tags:
      - CRM
  /crm/companies/{company_id}:
    delete:
      description: Delete a company.
      parameters:
      - in: path
        name: company_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete company
      tags:
      - CRM
    get:
      description: Get a single company.
      parameters:
      - in: path
        name: company_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCompany'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get company
      tags:
      - CRM
    patch:
      description: Update company fields.
      parameters:
      - in: path
        name: company_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmCompanyInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmCompany'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update company
      tags:
      - CRM
  /crm/contacts:
    get:
      description: Returns paginated contacts. Filter by `?lifecycle_stage=lead`,
        `?lead_source=organic`, `?q=name_or_email`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: lifecycle_stage
        schema:
          enum:
          - subscriber
          - lead
          - marketing_qualified_lead
          - sales_qualified_lead
          - opportunity
          - customer
          - evangelist
          type: string
      - in: query
        name: lead_source
        schema:
          type: string
      - description: Search by name, email, or company name
        in: query
        name: q
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmContact'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List contacts
      tags:
      - CRM
    post:
      description: Create a new CRM contact.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmContactInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmContact'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create contact
      tags:
      - CRM
  /crm/contacts/ingest:
    post:
      description: "The host's backend calls this to keep CRM contacts in sync with\
        \ its own\nusers — supplying signup / last-login / plan and arbitrary traits,\
        \ which\nJourneys target on (welcome-on-signup, win-back-on-inactivity, etc.).\n\
        \nBody: { email | external_uid (one required), first_name, last_name,\n  \
        \      company_name, company_external_uid, company_domain, company_tier,\n\
        \        company_mrr, company_arr, plan, signup_at, last_seen_at,\n      \
        \  lifecycle_stage, lead_source, traits {} }\n\nMatches an existing contact\
        \ by external_uid first, then email; creates one\nif none. A newly-created\
        \ contact fires the 'contact.created' journey\nenrollment trigger.\n\nWhen\
        \ company_external_uid is supplied, a Company record is upserted (keyed\n\
        by that id so two registrations sharing a company name stay distinct) and\n\
        the contact is linked to it. Returns {contact, created, company?,\ncompany_created?}."
      requestBody:
        content:
          application/json:
            example:
              company_domain: acme.com
              company_external_uid: acct_xyz789
              company_name: Acme Inc
              email: jane@example.com
              external_uid: usr_abc123
              first_name: Jane
              last_name: Doe
              last_seen_at: '2026-07-10T14:05:00Z'
              lead_source: organic
              lifecycle_stage: lead
              plan: pro
              signup_at: '2026-01-15T09:30:00Z'
              traits:
                segment: enterprise
            schema:
              properties:
                company_domain:
                  type: string
                company_external_uid:
                  type: string
                company_name:
                  type: string
                email:
                  type: string
                external_uid:
                  type: string
                first_name:
                  type: string
                last_name:
                  type: string
                last_seen_at:
                  type: string
                lead_source:
                  type: string
                lifecycle_stage:
                  type: string
                plan:
                  type: string
                signup_at:
                  type: string
                traits:
                  properties:
                    segment:
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  company:
                    address: 100 Main St
                    city: Boston
                    country: US
                    created_at: '2026-01-10T08:00:00+00:00'
                    description: Widget maker.
                    domain: acme.com
                    external_uid: acct_xyz789
                    id: 1
                    industry: SaaS
                    linkedin_url: https://linkedin.com/company/acme
                    name: Acme Inc
                    owner_id: 7
                    phone: +1-202-555-0111
                    size: 51-200
                    updated_at: '2026-07-01T12:00:00+00:00'
                    website: https://acme.com
                  company_created: true
                  contact:
                    city: Boston
                    company_name: Acme Inc
                    country: US
                    created_at: '2026-01-15T09:30:00+00:00'
                    description: Met at conference.
                    email: jane@example.com
                    external_uid: usr_abc123
                    first_name: Jane
                    full_name: Jane Doe
                    id: 1
                    is_unsubscribed: false
                    job_title: VP Engineering
                    last_name: Doe
                    last_seen_at: '2026-07-10T14:05:00+00:00'
                    lead_score: 42
                    lead_source: organic
                    lifecycle_stage: lead
                    linkedin_url: https://linkedin.com/in/janedoe
                    mobile: +1-202-555-0180
                    owner_id: 7
                    phone: +1-202-555-0100
                    plan: pro
                    signup_at: '2026-01-15T09:30:00+00:00'
                    tags:
                    - color: '#6b7280'
                      id: 1
                      name: VIP
                    traits:
                      segment: enterprise
                    twitter_handle: janedoe
                    updated_at: '2026-07-10T14:05:00+00:00'
                    website: https://example.com
                  created: true
              schema:
                properties:
                  data:
                    properties:
                      company:
                        properties:
                          address:
                            type: string
                          city:
                            type: string
                          country:
                            type: string
                          created_at:
                            type: string
                          description:
                            type: string
                          domain:
                            type: string
                          external_uid:
                            type: string
                          id:
                            type: integer
                          industry:
                            type: string
                          linkedin_url:
                            type: string
                          name:
                            type: string
                          owner_id:
                            type: integer
                          phone:
                            type: string
                          size:
                            type: string
                          updated_at:
                            type: string
                          website:
                            type: string
                        type: object
                      company_created:
                        type: boolean
                      contact:
                        properties:
                          city:
                            type: string
                          company_name:
                            type: string
                          country:
                            type: string
                          created_at:
                            type: string
                          description:
                            type: string
                          email:
                            type: string
                          external_uid:
                            type: string
                          first_name:
                            type: string
                          full_name:
                            type: string
                          id:
                            type: integer
                          is_unsubscribed:
                            type: boolean
                          job_title:
                            type: string
                          last_name:
                            type: string
                          last_seen_at:
                            type: string
                          lead_score:
                            type: integer
                          lead_source:
                            type: string
                          lifecycle_stage:
                            type: string
                          linkedin_url:
                            type: string
                          mobile:
                            type: string
                          owner_id:
                            type: integer
                          phone:
                            type: string
                          plan:
                            type: string
                          signup_at:
                            type: string
                          tags:
                            items:
                              properties:
                                color:
                                  type: string
                                id:
                                  type: integer
                                name:
                                  type: string
                              type: object
                            type: array
                          traits:
                            properties:
                              segment:
                                type: string
                            type: object
                          twitter_handle:
                            type: string
                          updated_at:
                            type: string
                          website:
                            type: string
                        type: object
                      created:
                        type: boolean
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Upsert a contact with product-usage data, for lifecycle Journeys.
      tags:
      - CRM
  /crm/contacts/{contact_id}:
    delete:
      description: Permanently delete a contact and all associated activities, notes,
        and tasks.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete contact
      tags:
      - CRM
    get:
      description: Get a single contact by ID.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmContact'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get contact
      tags:
      - CRM
    patch:
      description: Update contact fields. Pass only the fields you want to change.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmContactInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmContact'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update contact
      tags:
      - CRM
  /crm/contacts/{contact_id}/activities:
    get:
      description: Returns paginated activity log for a contact.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmActivity'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List contact activities
      tags:
      - CRM
  /crm/contacts/{contact_id}/notes:
    get:
      description: Returns paginated notes for a contact.
      parameters:
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmNote'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List contact notes
      tags:
      - CRM
  /crm/deals:
    get:
      description: 'Returns paginated deals. Filter: `?status=open|won|lost`, `?pipeline_id=N`,
        `?stage_id=N`, `?owner_id=N`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - open
          - won
          - lost
          type: string
      - in: query
        name: pipeline_id
        schema:
          type: integer
      - in: query
        name: stage_id
        schema:
          type: integer
      - in: query
        name: owner_id
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmDeal'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List deals
      tags:
      - CRM
    post:
      description: 'Create a new deal. Pass `contact_ids` and/or `company_ids` to
        link existing records.


        **Webhook events fired:** `crm.deal.created`'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmDealInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmDeal'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create deal
      tags:
      - CRM
  /crm/deals/{deal_id}:
    delete:
      description: Delete a deal and all its line items.
      parameters:
      - in: path
        name: deal_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete deal
      tags:
      - CRM
    get:
      description: Get a deal with linked contacts, companies, and product line items.
      parameters:
      - in: path
        name: deal_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmDeal'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get deal
      tags:
      - CRM
    patch:
      description: 'Update deal fields. Setting `status=won` or `status=lost` automatically
        records `closed_at`.


        **Webhook events fired:** `crm.deal.updated`, `crm.deal.stage_changed` (if
        stage changed), `crm.deal.won` or `crm.deal.lost` (if status changed to won/lost)'
      parameters:
      - in: path
        name: deal_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmDealInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmDeal'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update deal
      tags:
      - CRM
  /crm/forms:
    get:
      description: Returns all lead-capture forms.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmForm'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List forms
      tags:
      - CRM
  /crm/forms/{form_id}:
    get:
      description: Get a form with its fields and recent submissions.
      parameters:
      - in: path
        name: form_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmForm'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get form
      tags:
      - CRM
  /crm/forms/{form_id}/submissions:
    get:
      description: Returns paginated form submissions.
      parameters:
      - in: path
        name: form_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmForm'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List submissions
      tags:
      - CRM
  /crm/lists:
    get:
      description: Returns all contact lists (static and smart).
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmList'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List contact lists
      tags:
      - CRM
    post:
      description: Create a contact list.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmListInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmList'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create list
      tags:
      - CRM
  /crm/lists/{list_id}:
    delete:
      description: Delete a list. Contacts are not deleted.
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete list
      tags:
      - CRM
    get:
      description: Get a list with its member contacts.
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmList'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get list
      tags:
      - CRM
    patch:
      description: Update list name, description, or filter criteria.
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmListInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmList'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update list
      tags:
      - CRM
  /crm/lists/{list_id}/import:
    post:
      description: "Accepts **multipart/form-data** with:\n  - ``file``        – CSV\
        \ or Excel (.xlsx) file (optional when using ``contacts``)\n  - ``column_map``\
        \  – JSON object mapping file column names → contact fields (optional;\n \
        \                     omit or set ``auto_map=true`` to let the server figure\
        \ it out)\n  - ``auto_map``    – ``\"true\"`` to auto-detect column mapping\
        \ (default when omitting column_map)\n  - ``name``        – Import label (optional,\
        \ defaults to filename or \"API import\")\n\nAlternatively, send **application/json**\
        \ with:\n  - ``contacts``    – array of contact objects (fields: email, first_name,\
        \ last_name, phone,\n                      company_name, job_title, city,\
        \ country, tags)\n  - ``name``        – Import label (optional)\n\nReturns:\
        \ import summary with created/updated/skipped/errors counts."
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Import contacts into a list from a file upload or a JSON array.
      tags:
      - CRM
  /crm/lists/{list_id}/members:
    post:
      description: 'Add a contact to a list. Body: `{contact_id: N}`.'
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  type: integer
              required:
              - contact_id
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmList'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add member to list
      tags:
      - CRM
  /crm/lists/{list_id}/members/{contact_id}:
    delete:
      description: Remove a contact from a list.
      parameters:
      - in: path
        name: list_id
        required: true
        schema:
          type: integer
      - in: path
        name: contact_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Removed
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Remove member from list
      tags:
      - CRM
  /crm/notes:
    get:
      description: 'Returns paginated notes. Filter: `?contact_id=N`, `?company_id=N`,
        `?deal_id=N`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: contact_id
        schema:
          type: integer
      - in: query
        name: company_id
        schema:
          type: integer
      - in: query
        name: deal_id
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmNote'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List notes
      tags:
      - CRM
    post:
      description: Create a note on a contact, company, or deal.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmNoteInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmNote'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create note
      tags:
      - CRM
  /crm/notes/{note_id}:
    delete:
      description: Delete a note.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete note
      tags:
      - CRM
    patch:
      description: Update note body.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmNoteInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmNote'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update note
      tags:
      - CRM
  /crm/pipelines:
    get:
      description: Returns all sales pipelines with their stages.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmPipeline'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List pipelines
      tags:
      - CRM
    post:
      description: 'Create a pipeline. If `stages` is omitted, six default stages
        are created:

        New → Qualified → Proposal → Negotiation → Won → Lost'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmPipelineInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmPipeline'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create pipeline
      tags:
      - CRM
  /crm/pipelines/{pipeline_id}:
    delete:
      description: Delete a pipeline and all its stages. Deals are unlinked.
      parameters:
      - in: path
        name: pipeline_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete pipeline
      tags:
      - CRM
    patch:
      description: Update pipeline name, currency, or default flag.
      parameters:
      - in: path
        name: pipeline_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmPipelineInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmPipeline'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update pipeline
      tags:
      - CRM
  /crm/products:
    get:
      description: 'Returns paginated products. Filter: `?active=true`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: active
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmProduct'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List products
      tags:
      - CRM
    post:
      description: Add a product to the catalog.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmProductInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmProduct'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create product
      tags:
      - CRM
  /crm/products/{product_id}:
    delete:
      description: Delete a product from the catalog.
      parameters:
      - in: path
        name: product_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete product
      tags:
      - CRM
    patch:
      description: Update product details.
      parameters:
      - in: path
        name: product_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmProductInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmProduct'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update product
      tags:
      - CRM
  /crm/tags:
    get:
      description: Returns all CRM tags for the account.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmTag'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List tags
      tags:
      - CRM
    post:
      description: Create a new contact tag.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmTagInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmTag'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create tag
      tags:
      - CRM
  /crm/tags/{tag_id}:
    delete:
      description: Delete a tag and remove it from all contacts.
      parameters:
      - in: path
        name: tag_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete tag
      tags:
      - CRM
  /crm/tasks:
    get:
      description: 'Returns paginated tasks. Filter: `?status=open`, `?priority=high`,
        `?contact_id=N`, `?deal_id=N`.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - open
          - completed
          - cancelled
          type: string
      - in: query
        name: priority
        schema:
          enum:
          - low
          - medium
          - high
          - urgent
          type: string
      - in: query
        name: contact_id
        schema:
          type: integer
      - in: query
        name: company_id
        schema:
          type: integer
      - in: query
        name: deal_id
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/CrmTask'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List CRM tasks
      tags:
      - CRM
    post:
      description: Create a follow-up task.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmTaskInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmTask'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create CRM task
      tags:
      - CRM
  /crm/tasks/{task_id}:
    delete:
      description: Delete a task.
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete CRM task
      tags:
      - CRM
    patch:
      description: Update task fields. Set `status=completed` to mark done.
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmTaskInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/CrmTask'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update CRM task
      tags:
      - CRM
  /csm/accounts:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  accounts:
                  - arr: 24000
                    contract_end: '2027-01-15'
                    created_at: '2026-06-01T09:00:00+00:00'
                    crm_company_id: 5
                    csm_owner_id: 3
                    health_score: 82
                    health_status: healthy
                    id: 12
                    lifecycle_stage: onboarding
                    mrr: 2000
                    name: Acme Inc.
                    renewal_date: '2027-01-15'
                    support_account_id: null
                    updated_at: '2026-07-10T09:00:00+00:00'
                  page: 1
                  pages: 1
                  per_page: 25
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      accounts:
                        items:
                          properties:
                            arr:
                              type: number
                            contract_end:
                              type: string
                            created_at:
                              type: string
                            crm_company_id:
                              type: integer
                            csm_owner_id:
                              type: integer
                            health_score:
                              type: number
                            health_status:
                              type: string
                            id:
                              type: integer
                            lifecycle_stage:
                              type: string
                            mrr:
                              type: number
                            name:
                              type: string
                            renewal_date:
                              type: string
                            support_account_id:
                              nullable: true
                            updated_at:
                              type: string
                          type: object
                        type: array
                      page:
                        type: integer
                      pages:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List CSM accounts with optional filters.
      tags:
      - Customer Success (CSM)
    post:
      requestBody:
        content:
          application/json:
            example:
              arr: 24000
              crm_company_id: 5
              csm_owner_id: 3
              lifecycle_stage: onboarding
              mrr: 2000
              name: Acme Inc.
              renewal_date: '2027-01-15'
            schema:
              properties:
                arr:
                  type: integer
                crm_company_id:
                  type: integer
                csm_owner_id:
                  type: integer
                lifecycle_stage:
                  type: string
                mrr:
                  type: integer
                name:
                  type: string
                renewal_date:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  account:
                    arr: 24000
                    contract_end: '2027-01-15'
                    created_at: '2026-06-01T09:00:00+00:00'
                    crm_company_id: 5
                    csm_owner_id: 3
                    health_score: 82
                    health_status: healthy
                    id: 12
                    lifecycle_stage: onboarding
                    mrr: 2000
                    name: Acme Inc.
                    renewal_date: '2027-01-15'
                    support_account_id: null
                    updated_at: '2026-07-10T09:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      account:
                        properties:
                          arr:
                            type: number
                          contract_end:
                            type: string
                          created_at:
                            type: string
                          crm_company_id:
                            type: integer
                          csm_owner_id:
                            type: integer
                          health_score:
                            type: number
                          health_status:
                            type: string
                          id:
                            type: integer
                          lifecycle_stage:
                            type: string
                          mrr:
                            type: number
                          name:
                            type: string
                          renewal_date:
                            type: string
                          support_account_id:
                            nullable: true
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new CSM account.
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}:
    delete:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete csm accounts account_id
      tags:
      - Customer Success (CSM)
    get:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  account:
                    arr: 24000
                    contract_end: '2027-01-15'
                    created_at: '2026-06-01T09:00:00+00:00'
                    crm_company_id: 5
                    csm_owner_id: 3
                    health_score: 82
                    health_status: healthy
                    id: 12
                    lifecycle_stage: onboarding
                    mrr: 2000
                    name: Acme Inc.
                    renewal_date: '2027-01-15'
                    support_account_id: null
                    updated_at: '2026-07-10T09:00:00+00:00'
                  health_history:
                  - recorded_at: '2026-07-10T09:00:00+00:00'
                    score: 82
                    status: healthy
                  open_tasks: 2
                  total_engagements: 8
              schema:
                properties:
                  data:
                    properties:
                      account:
                        properties:
                          arr:
                            type: number
                          contract_end:
                            type: string
                          created_at:
                            type: string
                          crm_company_id:
                            type: integer
                          csm_owner_id:
                            type: integer
                          health_score:
                            type: number
                          health_status:
                            type: string
                          id:
                            type: integer
                          lifecycle_stage:
                            type: string
                          mrr:
                            type: number
                          name:
                            type: string
                          renewal_date:
                            type: string
                          support_account_id:
                            nullable: true
                          updated_at:
                            type: string
                        type: object
                      health_history:
                        items:
                          properties:
                            recorded_at:
                              type: string
                            score:
                              type: number
                            status:
                              type: string
                          type: object
                        type: array
                      open_tasks:
                        type: integer
                      total_engagements:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm accounts account_id
      tags:
      - Customer Success (CSM)
    patch:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              arr: 30000
              lifecycle_stage: active
              name: Acme Inc.
              renewal_date: '2027-02-01'
            schema:
              properties:
                arr:
                  type: integer
                lifecycle_stage:
                  type: string
                name:
                  type: string
                renewal_date:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  account:
                    arr: 24000
                    contract_end: '2027-01-15'
                    created_at: '2026-06-01T09:00:00+00:00'
                    crm_company_id: 5
                    csm_owner_id: 3
                    health_score: 82
                    health_status: healthy
                    id: 12
                    lifecycle_stage: onboarding
                    mrr: 2000
                    name: Acme Inc.
                    renewal_date: '2027-01-15'
                    support_account_id: null
                    updated_at: '2026-07-10T09:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      account:
                        properties:
                          arr:
                            type: number
                          contract_end:
                            type: string
                          created_at:
                            type: string
                          crm_company_id:
                            type: integer
                          csm_owner_id:
                            type: integer
                          health_score:
                            type: number
                          health_status:
                            type: string
                          id:
                            type: integer
                          lifecycle_stage:
                            type: string
                          mrr:
                            type: number
                          name:
                            type: string
                          renewal_date:
                            type: string
                          support_account_id:
                            nullable: true
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update csm accounts account_id
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/engagements:
    get:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  engagements:
                  - engagement_type: call
                    id: 4
                    logged_by_id: 3
                    notes: Went well.
                    occurred_at: '2026-07-10T09:00:00+00:00'
                    subject: Quarterly check-in
                  page: 1
                  per_page: 20
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      engagements:
                        items:
                          properties:
                            engagement_type:
                              type: string
                            id:
                              type: integer
                            logged_by_id:
                              type: integer
                            notes:
                              type: string
                            occurred_at:
                              type: string
                            subject:
                              type: string
                          type: object
                        type: array
                      page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm accounts account_id engagements
      tags:
      - Customer Success (CSM)
    post:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              engagement_type: call
              notes: Went well.
              subject: Quarterly check-in
            schema:
              properties:
                engagement_type:
                  type: string
                notes:
                  type: string
                subject:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  engagement:
                    engagement_type: call
                    id: 4
                    notes: Went well.
                    occurred_at: '2026-07-10T09:00:00+00:00'
                    subject: Quarterly check-in
              schema:
                properties:
                  data:
                    properties:
                      engagement:
                        properties:
                          engagement_type:
                            type: string
                          id:
                            type: integer
                          notes:
                            type: string
                          occurred_at:
                            type: string
                          subject:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create csm accounts account_id engagements
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/health:
    get:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  current_score: 82
                  current_status: healthy
                  history:
                  - recorded_at: '2026-07-10T09:00:00+00:00'
                    score: 82
                    status: healthy
              schema:
                properties:
                  data:
                    properties:
                      current_score:
                        type: number
                      current_status:
                        type: string
                      history:
                        items:
                          properties:
                            recorded_at:
                              type: string
                            score:
                              type: number
                            status:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm accounts account_id health
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/health/recalc:
    post:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  health_score: 82
                  health_status: healthy
              schema:
                properties:
                  data:
                    properties:
                      health_score:
                        type: number
                      health_status:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create csm accounts account_id health recalc
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/notes:
    get:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  notes:
                  - author_id: 3
                    content: Customer asked about SSO.
                    created_at: '2026-07-10T09:00:00+00:00'
                    id: 7
              schema:
                properties:
                  data:
                    properties:
                      notes:
                        items:
                          properties:
                            author_id:
                              type: integer
                            content:
                              type: string
                            created_at:
                              type: string
                            id:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm accounts account_id notes
      tags:
      - Customer Success (CSM)
    post:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content: Customer asked about SSO.
            schema:
              properties:
                content:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  note:
                    content: Customer asked about SSO.
                    created_at: '2026-07-10T09:00:00+00:00'
                    id: 7
              schema:
                properties:
                  data:
                    properties:
                      note:
                        properties:
                          content:
                            type: string
                          created_at:
                            type: string
                          id:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create csm accounts account_id notes
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/playbooks/start:
    post:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              playbook_id: 2
            schema:
              properties:
                playbook_id:
                  type: integer
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  account_id: 12
                  playbook_id: 2
                  playbook_name: Onboarding
                  run_id: 15
                  status: in_progress
                  steps: 5
              schema:
                properties:
                  data:
                    properties:
                      account_id:
                        type: integer
                      playbook_id:
                        type: integer
                      playbook_name:
                        type: string
                      run_id:
                        type: integer
                      status:
                        type: string
                      steps:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create csm accounts account_id playbooks start
      tags:
      - Customer Success (CSM)
  /csm/accounts/{account_id}/tasks:
    get:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  tasks:
                  - assigned_to_id: 3
                    due_date: '2026-08-01'
                    id: 9
                    is_complete: false
                    title: Schedule renewal call
              schema:
                properties:
                  data:
                    properties:
                      tasks:
                        items:
                          properties:
                            assigned_to_id:
                              type: integer
                            due_date:
                              type: string
                            id:
                              type: integer
                            is_complete:
                              type: boolean
                            title:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm accounts account_id tasks
      tags:
      - Customer Success (CSM)
    post:
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              assigned_to_id: 3
              due_date: '2026-08-01'
              title: Schedule renewal call
            schema:
              properties:
                assigned_to_id:
                  type: integer
                due_date:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  task:
                    due_date: '2026-08-01'
                    id: 9
                    is_complete: false
                    title: Schedule renewal call
              schema:
                properties:
                  data:
                    properties:
                      task:
                        properties:
                          due_date:
                            type: string
                          id:
                            type: integer
                          is_complete:
                            type: boolean
                          title:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create csm accounts account_id tasks
      tags:
      - Customer Success (CSM)
  /csm/playbooks:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  playbooks:
                  - description: New-customer onboarding.
                    id: 2
                    name: Onboarding
                    step_count: 5
                    trigger: lifecycle_stage
              schema:
                properties:
                  data:
                    properties:
                      playbooks:
                        items:
                          properties:
                            description:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            step_count:
                              type: integer
                            trigger:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get csm playbooks
      tags:
      - Customer Success (CSM)
  /csm/tasks/{task_id}/complete:
    patch:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  is_complete: true
                  task_id: 9
              schema:
                properties:
                  data:
                    properties:
                      is_complete:
                        type: boolean
                      task_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update csm tasks task_id complete
      tags:
      - Customer Success (CSM)
  /directory/departments:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - head: Dana Lee
                  id: dp1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4050
                  member_count: 18
                  name: Engineering
                  parent_id: null
              schema:
                properties:
                  data:
                    items:
                      properties:
                        head:
                          type: string
                        id:
                          type: string
                        member_count:
                          type: integer
                        name:
                          type: string
                        parent_id:
                          nullable: true
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get directory departments
      tags:
      - Employee Directory
  /directory/employees:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - bio: Building the platform core.
                  department: Engineering
                  department_id: dp1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4050
                  email: alex.rivera@example.com
                  employment_type: full_time
                  id: u1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6072
                  job_title: Staff Engineer
                  location: Remote - US
                  manager: Dana Lee
                  manager_email: dana.lee@example.com
                  name: Alex Rivera
                  pronouns: she/her
                  skills:
                  - Python
                  - Flask
                  - Postgres
                  social_links:
                    linkedin: https://linkedin.com/in/alexrivera
                  start_date: '2024-03-01'
                  status: active
                  visibility: org
                  work_phone: +1-555-0142
              schema:
                properties:
                  data:
                    items:
                      properties:
                        bio:
                          type: string
                        department:
                          type: string
                        department_id:
                          type: string
                        email:
                          type: string
                        employment_type:
                          type: string
                        id:
                          type: string
                        job_title:
                          type: string
                        location:
                          type: string
                        manager:
                          type: string
                        manager_email:
                          type: string
                        name:
                          type: string
                        pronouns:
                          type: string
                        skills:
                          items:
                            type: string
                          type: array
                        social_links:
                          properties:
                            linkedin:
                              type: string
                          type: object
                        start_date:
                          type: string
                        status:
                          type: string
                        visibility:
                          type: string
                        work_phone:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List employees. Optional ?q=, ?department=<dept uid>.
      tags:
      - Employee Directory
  /directory/employees/{user_uid}:
    get:
      parameters:
      - in: path
        name: user_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  bio: Building the platform core.
                  department: Engineering
                  department_id: dp1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4050
                  email: alex.rivera@example.com
                  employment_type: full_time
                  id: u1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6072
                  job_title: Staff Engineer
                  location: Remote - US
                  manager: Dana Lee
                  manager_email: dana.lee@example.com
                  name: Alex Rivera
                  pronouns: she/her
                  skills:
                  - Python
                  - Flask
                  - Postgres
                  social_links:
                    linkedin: https://linkedin.com/in/alexrivera
                  start_date: '2024-03-01'
                  status: active
                  visibility: org
                  work_phone: +1-555-0142
              schema:
                properties:
                  data:
                    properties:
                      bio:
                        type: string
                      department:
                        type: string
                      department_id:
                        type: string
                      email:
                        type: string
                      employment_type:
                        type: string
                      id:
                        type: string
                      job_title:
                        type: string
                      location:
                        type: string
                      manager:
                        type: string
                      manager_email:
                        type: string
                      name:
                        type: string
                      pronouns:
                        type: string
                      skills:
                        items:
                          type: string
                        type: array
                      social_links:
                        properties:
                          linkedin:
                            type: string
                        type: object
                      start_date:
                        type: string
                      status:
                        type: string
                      visibility:
                        type: string
                      work_phone:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get directory employees user_uid
      tags:
      - Employee Directory
  /directory/org-chart:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - email: dana.lee@example.com
                  id: u1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6072
                  name: Dana Lee
                  reports:
                  - email: alex.rivera@example.com
                    id: u2b3c4d5-6e7f-8091-0a2b-3c4d5e6f7083
                    name: Alex Rivera
                    reports: []
                    title: Staff Engineer
                  title: VP Engineering
              schema:
                properties:
                  data:
                    items:
                      properties:
                        email:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        reports:
                          items:
                            properties:
                              email:
                                type: string
                              id:
                                type: string
                              name:
                                type: string
                              reports:
                                items: {}
                                type: array
                              title:
                                type: string
                            type: object
                          type: array
                        title:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Nested reporting tree. Optional ?root=<user uid> to focus a subtree.
      tags:
      - Employee Directory
  /editions/custom-fields:
    get:
      description: Optional query param ?project_key=BACK to filter to fields that
        apply to a project.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - field_type: dropdown
                  id: bb22cc33-0000-1111-2222-333344445555
                  is_enabled: true
                  is_required: false
                  options:
                  - Minor
                  - Major
                  - Critical
                  order: 0
                  title: Severity
                  tooltip: Bug severity level
              schema:
                properties:
                  data:
                    items:
                      properties:
                        field_type:
                          type: string
                        id:
                          type: string
                        is_enabled:
                          type: boolean
                        is_required:
                          type: boolean
                        options:
                          items:
                            type: string
                          type: array
                        order:
                          type: integer
                        title:
                          type: string
                        tooltip:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all edition custom field definitions for the account.
      tags:
      - Issue Tracking
    post:
      description: "Body (JSON):\n  title        string  required\n  field_type  \
        \ string  required  short_text|long_text|dropdown|yes_no\n  tooltip      string\
        \  optional\n  is_required  bool    optional  default false\n  scope     \
        \   string  optional  global|projects  default global\n  project_keys list\
        \    optional  required when scope=projects\n  options      list    optional\
        \  required when field_type=dropdown"
      requestBody:
        content:
          application/json:
            example:
              field_type: dropdown
              is_required: false
              options:
              - Minor
              - Major
              - Critical
              scope: global
              title: Severity
              tooltip: Bug severity level
            schema:
              properties:
                field_type:
                  type: string
                is_required:
                  type: boolean
                options:
                  items:
                    type: string
                  type: array
                scope:
                  type: string
                title:
                  type: string
                tooltip:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  field_type: dropdown
                  id: bb22cc33-0000-1111-2222-333344445555
                  is_enabled: true
                  is_required: false
                  options:
                  - Minor
                  - Major
                  - Critical
                  order: 0
                  title: Severity
                  tooltip: Bug severity level
              schema:
                properties:
                  data:
                    properties:
                      field_type:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      is_required:
                        type: boolean
                      options:
                        items:
                          type: string
                        type: array
                      order:
                        type: integer
                      title:
                        type: string
                      tooltip:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new edition custom field definition.
      tags:
      - Issue Tracking
  /editions/custom-fields/{field_id}:
    delete:
      parameters:
      - in: path
        name: field_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: bb22cc33-0000-1111-2222-333344445555
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an edition custom field and all its stored values.
      tags:
      - Issue Tracking
    patch:
      description: "Body (JSON, all fields optional):\n  title, tooltip, is_required,\
        \ is_enabled, options (list), scope, project_keys"
      parameters:
      - in: path
        name: field_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              is_enabled: true
              is_required: true
              options:
              - Minor
              - Major
              - Critical
              title: Severity
              tooltip: Bug severity level
            schema:
              properties:
                is_enabled:
                  type: boolean
                is_required:
                  type: boolean
                options:
                  items:
                    type: string
                  type: array
                title:
                  type: string
                tooltip:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  field_type: dropdown
                  id: bb22cc33-0000-1111-2222-333344445555
                  is_enabled: true
                  is_required: false
                  options:
                  - Minor
                  - Major
                  - Critical
                  order: 0
                  title: Severity
                  tooltip: Bug severity level
              schema:
                properties:
                  data:
                    properties:
                      field_type:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      is_required:
                        type: boolean
                      options:
                        items:
                          type: string
                        type: array
                      order:
                        type: integer
                      title:
                        type: string
                      tooltip:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update an edition custom field.
      tags:
      - Issue Tracking
  /editions/initiatives:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#6366f1'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Grow user activation
                  health: on_track
                  id: 4
                  name: Q3 Growth
                  owner:
                    id: 7
                    name: Ada Lovelace
                  project_count: 3
                  status: planned
                  target_date: '2026-09-30'
                  updated_at: '2026-07-10T09:00:00Z'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        created_at:
                          type: string
                        description:
                          type: string
                        health:
                          type: string
                        id:
                          type: integer
                        name:
                          type: string
                        owner:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        project_count:
                          type: integer
                        status:
                          type: string
                        target_date:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all initiatives for this account.
      tags:
      - Issue Tracking
    post:
      requestBody:
        content:
          application/json:
            example:
              color: '#6366f1'
              description: Grow user activation
              health: on_track
              name: Q3 Growth
              owner_id: 7
              status: planned
              target_date: '2026-09-30'
            schema:
              properties:
                color:
                  type: string
                description:
                  type: string
                health:
                  type: string
                name:
                  type: string
                owner_id:
                  type: integer
                status:
                  type: string
                target_date:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#6366f1'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Grow user activation
                  health: on_track
                  id: 4
                  name: Q3 Growth
                  owner:
                    id: 7
                    name: Ada Lovelace
                  project_count: 3
                  status: planned
                  target_date: '2026-09-30'
                  updated_at: '2026-07-10T09:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      health:
                        type: string
                      id:
                        type: integer
                      name:
                        type: string
                      owner:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      project_count:
                        type: integer
                      status:
                        type: string
                      target_date:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create an initiative.
      tags:
      - Issue Tracking
  /editions/initiatives/{ini_id}:
    delete:
      parameters:
      - in: path
        name: ini_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  initiative_id: 4
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      initiative_id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an initiative.
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: ini_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              health: on_track
              name: Q3 Growth
            schema:
              properties:
                health:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#6366f1'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Grow user activation
                  health: on_track
                  id: 4
                  name: Q3 Growth
                  owner:
                    id: 7
                    name: Ada Lovelace
                  project_count: 3
                  status: planned
                  target_date: '2026-09-30'
                  updated_at: '2026-07-10T09:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      health:
                        type: string
                      id:
                        type: integer
                      name:
                        type: string
                      owner:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      project_count:
                        type: integer
                      status:
                        type: string
                      target_date:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update an initiative.
      tags:
      - Issue Tracking
  /editions/labels:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#6b7280'
                  id: 3
                  name: backend
                  project_id: 1
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        id:
                          type: integer
                        name:
                          type: string
                        project_id:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all edition labels for this account (tenant-wide + project-scoped).
      tags:
      - Issue Tracking
    post:
      requestBody:
        content:
          application/json:
            example:
              color: '#6b7280'
              name: backend
              project_key: ENG
            schema:
              properties:
                color:
                  type: string
                name:
                  type: string
                project_key:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#6b7280'
                  id: 3
                  name: backend
                  project_id: 1
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      id:
                        type: integer
                      name:
                        type: string
                      project_id:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a label (optionally scoped to a project).
      tags:
      - Issue Tracking
  /editions/projects:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#3b82f6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Core product engineering
                  icon: bi-kanban
                  id: 1
                  is_private: false
                  issue_count: 42
                  key: ENG
                  lead:
                    id: 7
                    name: Ada Lovelace
                  name: Engineering
                  status: active
                  target_date: '2026-12-31'
                  updated_at: '2026-07-15T12:30:00Z'
                  workflow_id: 2
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        created_at:
                          type: string
                        description:
                          type: string
                        icon:
                          type: string
                        id:
                          type: integer
                        is_private:
                          type: boolean
                        issue_count:
                          type: integer
                        key:
                          type: string
                        lead:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        name:
                          type: string
                        status:
                          type: string
                        target_date:
                          type: string
                        updated_at:
                          type: string
                        workflow_id:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all Issue Tracking projects for this account.
      tags:
      - Issue Tracking
    post:
      requestBody:
        content:
          application/json:
            example:
              color: '#3b82f6'
              description: Core product engineering
              icon: bi-kanban
              is_private: false
              key: ENG
              name: Engineering
              status: active
            schema:
              properties:
                color:
                  type: string
                description:
                  type: string
                icon:
                  type: string
                is_private:
                  type: boolean
                key:
                  type: string
                name:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#3b82f6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Core product engineering
                  icon: bi-kanban
                  id: 1
                  is_private: false
                  issue_count: 42
                  key: ENG
                  lead:
                    id: 7
                    name: Ada Lovelace
                  name: Engineering
                  status: active
                  target_date: '2026-12-31'
                  updated_at: '2026-07-15T12:30:00Z'
                  workflow_id: 2
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: integer
                      is_private:
                        type: boolean
                      issue_count:
                        type: integer
                      key:
                        type: string
                      lead:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      name:
                        type: string
                      status:
                        type: string
                      target_date:
                        type: string
                      updated_at:
                        type: string
                      workflow_id:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new Issue Tracking project.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}:
    delete:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  key: ENG
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      key:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a project and all its editions (irreversible).
      tags:
      - Issue Tracking
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#3b82f6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Core product engineering
                  icon: bi-kanban
                  id: 1
                  is_private: false
                  issue_count: 42
                  key: ENG
                  lead:
                    id: 7
                    name: Ada Lovelace
                  name: Engineering
                  status: active
                  target_date: '2026-12-31'
                  updated_at: '2026-07-15T12:30:00Z'
                  workflow_id: 2
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: integer
                      is_private:
                        type: boolean
                      issue_count:
                        type: integer
                      key:
                        type: string
                      lead:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      name:
                        type: string
                      status:
                        type: string
                      target_date:
                        type: string
                      updated_at:
                        type: string
                      workflow_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a project by its key.
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: Engineering
              status: active
              target_date: '2026-12-31'
            schema:
              properties:
                name:
                  type: string
                status:
                  type: string
                target_date:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#3b82f6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Core product engineering
                  icon: bi-kanban
                  id: 1
                  is_private: false
                  issue_count: 42
                  key: ENG
                  lead:
                    id: 7
                    name: Ada Lovelace
                  name: Engineering
                  status: active
                  target_date: '2026-12-31'
                  updated_at: '2026-07-15T12:30:00Z'
                  workflow_id: 2
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: integer
                      is_private:
                        type: boolean
                      issue_count:
                        type: integer
                      key:
                        type: string
                      lead:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      name:
                        type: string
                      status:
                        type: string
                      target_date:
                        type: string
                      updated_at:
                        type: string
                      workflow_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update project fields.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/custom-fields:
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - field_type: dropdown
                  id: bb22cc33-0000-1111-2222-333344445555
                  is_enabled: true
                  is_required: false
                  options:
                  - Minor
                  - Major
                  - Critical
                  order: 0
                  title: Severity
                  tooltip: Bug severity level
              schema:
                properties:
                  data:
                    items:
                      properties:
                        field_type:
                          type: string
                        id:
                          type: string
                        is_enabled:
                          type: boolean
                        is_required:
                          type: boolean
                        options:
                          items:
                            type: string
                          type: array
                        order:
                          type: integer
                        title:
                          type: string
                        tooltip:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all enabled custom fields that apply to a specific edition project.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions:
    get:
      description: "Query params:\n  status_id, assignee_id, priority, issue_type,\
        \ epic_id,\n  milestone_id, sprint_id, is_archived (default false),\n  q (title\
        \ search), page, per_page"
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - assignee:
                    id: 7
                    name: Ada Lovelace
                  comment_count: 4
                  created_at: '2026-07-10T08:00:00Z'
                  created_by:
                    id: 7
                    name: Ada Lovelace
                  due_date: '2026-07-20'
                  epic_id: 3
                  estimate: 3
                  id: 101
                  identifier: ENG-14
                  is_archived: false
                  issue_type: bug
                  labels:
                  - color: '#6b7280'
                    id: 3
                    name: backend
                    project_id: 1
                  milestone_id: 2
                  number: 14
                  parent_id: null
                  priority: high
                  project_id: 1
                  project_key: ENG
                  resolved_at: null
                  status:
                    category: started
                    color: '#f59e0b'
                    id: 5
                    is_terminal: false
                    name: In Progress
                    position: 2
                    workflow_id: 2
                  title: Fix login redirect
                  updated_at: '2026-07-15T11:00:00Z'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        assignee:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        comment_count:
                          type: integer
                        created_at:
                          type: string
                        created_by:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        due_date:
                          type: string
                        epic_id:
                          type: integer
                        estimate:
                          type: integer
                        id:
                          type: integer
                        identifier:
                          type: string
                        is_archived:
                          type: boolean
                        issue_type:
                          type: string
                        labels:
                          items:
                            properties:
                              color:
                                type: string
                              id:
                                type: integer
                              name:
                                type: string
                              project_id:
                                type: integer
                            type: object
                          type: array
                        milestone_id:
                          type: integer
                        number:
                          type: integer
                        parent_id:
                          nullable: true
                        priority:
                          type: string
                        project_id:
                          type: integer
                        project_key:
                          type: string
                        resolved_at:
                          nullable: true
                        status:
                          properties:
                            category:
                              type: string
                            color:
                              type: string
                            id:
                              type: integer
                            is_terminal:
                              type: boolean
                            name:
                              type: string
                            position:
                              type: integer
                            workflow_id:
                              type: integer
                          type: object
                        title:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List editions in a project.
      tags:
      - Issue Tracking
    post:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              assignee_id: 7
              body: <p>Steps to reproduce.</p>
              due_date: '2026-07-20'
              epic_id: 3
              estimate: 3
              issue_type: bug
              milestone_id: 2
              priority: high
              status_id: 5
              title: Fix login redirect
            schema:
              properties:
                assignee_id:
                  type: integer
                body:
                  type: string
                due_date:
                  type: string
                epic_id:
                  type: integer
                estimate:
                  type: integer
                issue_type:
                  type: string
                milestone_id:
                  type: integer
                priority:
                  type: string
                status_id:
                  type: integer
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Steps to reproduce the login redirect bug.</p>
                  comment_count: 4
                  created_at: '2026-07-10T08:00:00Z'
                  created_by:
                    id: 7
                    name: Ada Lovelace
                  custom_fields:
                  - field_id: 1
                    field_name: Severity
                    field_type: select
                    value: S2
                  due_date: '2026-07-20'
                  epic_id: 3
                  estimate: 3
                  id: 101
                  identifier: ENG-14
                  is_archived: false
                  issue_type: bug
                  labels:
                  - color: '#6b7280'
                    id: 3
                    name: backend
                    project_id: 1
                  milestone_id: 2
                  number: 14
                  parent_id: null
                  priority: high
                  project_id: 1
                  project_key: ENG
                  resolved_at: null
                  sprints:
                  - id: 9
                    name: Sprint 12
                  status:
                    category: started
                    color: '#f59e0b'
                    id: 5
                    is_terminal: false
                    name: In Progress
                    position: 2
                    workflow_id: 2
                  sub_issues:
                  - id: 102
                    identifier: ENG-15
                    status:
                      category: started
                      color: '#f59e0b'
                      id: 5
                      is_terminal: false
                      name: In Progress
                      position: 2
                      workflow_id: 2
                    title: Add regression test
                  title: Fix login redirect
                  updated_at: '2026-07-15T11:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      body:
                        type: string
                      comment_count:
                        type: integer
                      created_at:
                        type: string
                      created_by:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      custom_fields:
                        items:
                          properties:
                            field_id:
                              type: integer
                            field_name:
                              type: string
                            field_type:
                              type: string
                            value:
                              type: string
                          type: object
                        type: array
                      due_date:
                        type: string
                      epic_id:
                        type: integer
                      estimate:
                        type: integer
                      id:
                        type: integer
                      identifier:
                        type: string
                      is_archived:
                        type: boolean
                      issue_type:
                        type: string
                      labels:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            project_id:
                              type: integer
                          type: object
                        type: array
                      milestone_id:
                        type: integer
                      number:
                        type: integer
                      parent_id:
                        nullable: true
                      priority:
                        type: string
                      project_id:
                        type: integer
                      project_key:
                        type: string
                      resolved_at:
                        nullable: true
                      sprints:
                        items:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        type: array
                      status:
                        properties:
                          category:
                            type: string
                          color:
                            type: string
                          id:
                            type: integer
                          is_terminal:
                            type: boolean
                          name:
                            type: string
                          position:
                            type: integer
                          workflow_id:
                            type: integer
                        type: object
                      sub_issues:
                        items:
                          properties:
                            id:
                              type: integer
                            identifier:
                              type: string
                            status:
                              properties:
                                category:
                                  type: string
                                color:
                                  type: string
                                id:
                                  type: integer
                                is_terminal:
                                  type: boolean
                                name:
                                  type: string
                                position:
                                  type: integer
                                workflow_id:
                                  type: integer
                              type: object
                            title:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new edition in a project.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}:
    delete:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  identifier: ENG-14
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      identifier:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an edition permanently.
      tags:
      - Issue Tracking
    get:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Steps to reproduce the login redirect bug.</p>
                  comment_count: 4
                  created_at: '2026-07-10T08:00:00Z'
                  created_by:
                    id: 7
                    name: Ada Lovelace
                  custom_fields:
                  - field_id: 1
                    field_name: Severity
                    field_type: select
                    value: S2
                  due_date: '2026-07-20'
                  epic_id: 3
                  estimate: 3
                  id: 101
                  identifier: ENG-14
                  is_archived: false
                  issue_type: bug
                  labels:
                  - color: '#6b7280'
                    id: 3
                    name: backend
                    project_id: 1
                  milestone_id: 2
                  number: 14
                  parent_id: null
                  priority: high
                  project_id: 1
                  project_key: ENG
                  resolved_at: null
                  sprints:
                  - id: 9
                    name: Sprint 12
                  status:
                    category: started
                    color: '#f59e0b'
                    id: 5
                    is_terminal: false
                    name: In Progress
                    position: 2
                    workflow_id: 2
                  sub_issues:
                  - id: 102
                    identifier: ENG-15
                    status:
                      category: started
                      color: '#f59e0b'
                      id: 5
                      is_terminal: false
                      name: In Progress
                      position: 2
                      workflow_id: 2
                    title: Add regression test
                  title: Fix login redirect
                  updated_at: '2026-07-15T11:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      body:
                        type: string
                      comment_count:
                        type: integer
                      created_at:
                        type: string
                      created_by:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      custom_fields:
                        items:
                          properties:
                            field_id:
                              type: integer
                            field_name:
                              type: string
                            field_type:
                              type: string
                            value:
                              type: string
                          type: object
                        type: array
                      due_date:
                        type: string
                      epic_id:
                        type: integer
                      estimate:
                        type: integer
                      id:
                        type: integer
                      identifier:
                        type: string
                      is_archived:
                        type: boolean
                      issue_type:
                        type: string
                      labels:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            project_id:
                              type: integer
                          type: object
                        type: array
                      milestone_id:
                        type: integer
                      number:
                        type: integer
                      parent_id:
                        nullable: true
                      priority:
                        type: string
                      project_id:
                        type: integer
                      project_key:
                        type: string
                      resolved_at:
                        nullable: true
                      sprints:
                        items:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        type: array
                      status:
                        properties:
                          category:
                            type: string
                          color:
                            type: string
                          id:
                            type: integer
                          is_terminal:
                            type: boolean
                          name:
                            type: string
                          position:
                            type: integer
                          workflow_id:
                            type: integer
                        type: object
                      sub_issues:
                        items:
                          properties:
                            id:
                              type: integer
                            identifier:
                              type: string
                            status:
                              properties:
                                category:
                                  type: string
                                color:
                                  type: string
                                id:
                                  type: integer
                                is_terminal:
                                  type: boolean
                                name:
                                  type: string
                                position:
                                  type: integer
                                workflow_id:
                                  type: integer
                              type: object
                            title:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get full edition detail.
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              assignee_id: 7
              priority: high
              status_id: 6
              title: Fix login redirect
            schema:
              properties:
                assignee_id:
                  type: integer
                priority:
                  type: string
                status_id:
                  type: integer
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Steps to reproduce the login redirect bug.</p>
                  comment_count: 4
                  created_at: '2026-07-10T08:00:00Z'
                  created_by:
                    id: 7
                    name: Ada Lovelace
                  custom_fields:
                  - field_id: 1
                    field_name: Severity
                    field_type: select
                    value: S2
                  due_date: '2026-07-20'
                  epic_id: 3
                  estimate: 3
                  id: 101
                  identifier: ENG-14
                  is_archived: false
                  issue_type: bug
                  labels:
                  - color: '#6b7280'
                    id: 3
                    name: backend
                    project_id: 1
                  milestone_id: 2
                  number: 14
                  parent_id: null
                  priority: high
                  project_id: 1
                  project_key: ENG
                  resolved_at: null
                  sprints:
                  - id: 9
                    name: Sprint 12
                  status:
                    category: started
                    color: '#f59e0b'
                    id: 5
                    is_terminal: false
                    name: In Progress
                    position: 2
                    workflow_id: 2
                  sub_issues:
                  - id: 102
                    identifier: ENG-15
                    status:
                      category: started
                      color: '#f59e0b'
                      id: 5
                      is_terminal: false
                      name: In Progress
                      position: 2
                      workflow_id: 2
                    title: Add regression test
                  title: Fix login redirect
                  updated_at: '2026-07-15T11:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      body:
                        type: string
                      comment_count:
                        type: integer
                      created_at:
                        type: string
                      created_by:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      custom_fields:
                        items:
                          properties:
                            field_id:
                              type: integer
                            field_name:
                              type: string
                            field_type:
                              type: string
                            value:
                              type: string
                          type: object
                        type: array
                      due_date:
                        type: string
                      epic_id:
                        type: integer
                      estimate:
                        type: integer
                      id:
                        type: integer
                      identifier:
                        type: string
                      is_archived:
                        type: boolean
                      issue_type:
                        type: string
                      labels:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: integer
                            name:
                              type: string
                            project_id:
                              type: integer
                          type: object
                        type: array
                      milestone_id:
                        type: integer
                      number:
                        type: integer
                      parent_id:
                        nullable: true
                      priority:
                        type: string
                      project_id:
                        type: integer
                      project_key:
                        type: string
                      resolved_at:
                        nullable: true
                      sprints:
                        items:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        type: array
                      status:
                        properties:
                          category:
                            type: string
                          color:
                            type: string
                          id:
                            type: integer
                          is_terminal:
                            type: boolean
                          name:
                            type: string
                          position:
                            type: integer
                          workflow_id:
                            type: integer
                        type: object
                      sub_issues:
                        items:
                          properties:
                            id:
                              type: integer
                            identifier:
                              type: string
                            status:
                              properties:
                                category:
                                  type: string
                                color:
                                  type: string
                                id:
                                  type: integer
                                is_terminal:
                                  type: boolean
                                name:
                                  type: string
                                position:
                                  type: integer
                                workflow_id:
                                  type: integer
                              type: object
                            title:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update edition fields.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}/activity:
    get:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - action: status_changed
                  actor:
                    id: 7
                    name: Ada Lovelace
                  created_at: '2026-07-15T10:30:00Z'
                  id: 55
                  issue_id: 101
                  new_value: Done
                  note: null
                  old_value: In Progress
              schema:
                properties:
                  data:
                    items:
                      properties:
                        action:
                          type: string
                        actor:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        created_at:
                          type: string
                        id:
                          type: integer
                        issue_id:
                          type: integer
                        new_value:
                          type: string
                        note:
                          nullable: true
                        old_value:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Return the activity/audit log for an edition.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}/comments:
    get:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - author:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Looks good to me.</p>
                  created_at: '2026-07-15T10:00:00Z'
                  id: c_ab12
                  issue_id: 101
                  updated_at: '2026-07-15T10:05:00Z'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        author:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        body:
                          type: string
                        created_at:
                          type: string
                        id:
                          type: string
                        issue_id:
                          type: integer
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List comments on an edition.
      tags:
      - Issue Tracking
    post:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Looks good to me.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  author:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Looks good to me.</p>
                  created_at: '2026-07-15T10:00:00Z'
                  id: c_ab12
                  issue_id: 101
                  updated_at: '2026-07-15T10:05:00Z'
              schema:
                properties:
                  data:
                    properties:
                      author:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      body:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: string
                      issue_id:
                        type: integer
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add a comment to an edition.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}/comments/{comment_id}:
    delete:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: path
        name: comment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  comment_id: c_ab12
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      comment_id:
                        type: string
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a comment.
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: path
        name: comment_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Looks good to me.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  author:
                    id: 7
                    name: Ada Lovelace
                  body: <p>Looks good to me.</p>
                  created_at: '2026-07-15T10:00:00Z'
                  id: c_ab12
                  issue_id: 101
                  updated_at: '2026-07-15T10:05:00Z'
              schema:
                properties:
                  data:
                    properties:
                      author:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      body:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: string
                      issue_id:
                        type: integer
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Edit a comment (author only).
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}/custom-field-values:
    post:
      description: "Body (JSON):\n  values: { \"<field_uuid>\": \"<value_text>\",\
        \ ... }\n  Pass null or empty string to clear a field."
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              values:
                bb22cc33-0000-1111-2222-333344445555: Critical
            schema:
              properties:
                values:
                  properties:
                    bb22cc33-0000-1111-2222-333344445555:
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  edition: BACK-42
                  saved:
                  - field_id: bb22cc33-0000-1111-2222-333344445555
                    value: Critical
              schema:
                properties:
                  data:
                    properties:
                      edition:
                        type: string
                      saved:
                        items:
                          properties:
                            field_id:
                              type: string
                            value:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Bulk-upsert custom field values for an edition.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/editions/{issue_num}/status:
    post:
      description: 'Body: { "status_id": <int> }'
      parameters:
      - in: path
        name: issue_num
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              status_id: 6
            schema:
              properties:
                status_id:
                  type: integer
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  identifier: ENG-14
                  issue_id: 101
                  status:
                    category: completed
                    color: '#10b981'
                    id: 6
                    is_terminal: true
                    name: Done
                    position: 4
                    workflow_id: 2
              schema:
                properties:
                  data:
                    properties:
                      identifier:
                        type: string
                      issue_id:
                        type: integer
                      status:
                        properties:
                          category:
                            type: string
                          color:
                            type: string
                          id:
                            type: integer
                          is_terminal:
                            type: boolean
                          name:
                            type: string
                          position:
                            type: integer
                          workflow_id:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Transition an edition to a new status.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/epics:
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#8b5cf6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Overhaul all auth flows
                  id: 3
                  issue_count: 12
                  project_id: 1
                  start_date: '2026-07-01'
                  status: open
                  target_date: '2026-09-30'
                  title: Authentication revamp
                  updated_at: '2026-07-14T09:00:00Z'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        created_at:
                          type: string
                        description:
                          type: string
                        id:
                          type: integer
                        issue_count:
                          type: integer
                        project_id:
                          type: integer
                        start_date:
                          type: string
                        status:
                          type: string
                        target_date:
                          type: string
                        title:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List epics in a project.
      tags:
      - Issue Tracking
    post:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              color: '#8b5cf6'
              description: Overhaul all auth flows
              start_date: '2026-07-01'
              status: open
              target_date: '2026-09-30'
              title: Authentication revamp
            schema:
              properties:
                color:
                  type: string
                description:
                  type: string
                start_date:
                  type: string
                status:
                  type: string
                target_date:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#8b5cf6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Overhaul all auth flows
                  id: 3
                  issue_count: 12
                  project_id: 1
                  start_date: '2026-07-01'
                  status: open
                  target_date: '2026-09-30'
                  title: Authentication revamp
                  updated_at: '2026-07-14T09:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      project_id:
                        type: integer
                      start_date:
                        type: string
                      status:
                        type: string
                      target_date:
                        type: string
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create an epic.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/epics/{epic_id}:
    delete:
      parameters:
      - in: path
        name: epic_id
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  epic_id: 3
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      epic_id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an epic (editions are unlinked, not deleted).
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: epic_id
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              status: open
              title: Authentication revamp
            schema:
              properties:
                status:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#8b5cf6'
                  created_at: '2026-07-01T09:00:00Z'
                  description: Overhaul all auth flows
                  id: 3
                  issue_count: 12
                  project_id: 1
                  start_date: '2026-07-01'
                  status: open
                  target_date: '2026-09-30'
                  title: Authentication revamp
                  updated_at: '2026-07-14T09:00:00Z'
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      project_id:
                        type: integer
                      start_date:
                        type: string
                      status:
                        type: string
                      target_date:
                        type: string
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update an epic.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/milestones:
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T09:00:00Z'
                  description: Major release milestone
                  id: 2
                  issue_count: 8
                  project_id: 1
                  status: open
                  target_date: '2026-10-15'
                  title: v2.0 Release
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        description:
                          type: string
                        id:
                          type: integer
                        issue_count:
                          type: integer
                        project_id:
                          type: integer
                        status:
                          type: string
                        target_date:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List milestones in a project.
      tags:
      - Issue Tracking
    post:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: Major release milestone
              status: open
              target_date: '2026-10-15'
              title: v2.0 Release
            schema:
              properties:
                description:
                  type: string
                status:
                  type: string
                target_date:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:00:00Z'
                  description: Major release milestone
                  id: 2
                  issue_count: 8
                  project_id: 1
                  status: open
                  target_date: '2026-10-15'
                  title: v2.0 Release
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      project_id:
                        type: integer
                      status:
                        type: string
                      target_date:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a milestone.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/milestones/{ms_id}:
    delete:
      parameters:
      - in: path
        name: ms_id
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  milestone_id: 2
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      milestone_id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a milestone.
      tags:
      - Issue Tracking
    patch:
      parameters:
      - in: path
        name: ms_id
        required: true
        schema:
          type: string
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              status: open
              title: v2.0 Release
            schema:
              properties:
                status:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:00:00Z'
                  description: Major release milestone
                  id: 2
                  issue_count: 8
                  project_id: 1
                  status: open
                  target_date: '2026-10-15'
                  title: v2.0 Release
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      project_id:
                        type: integer
                      status:
                        type: string
                      target_date:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a milestone.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/sprints:
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-14T09:00:00Z'
                  end_date: '2026-07-28'
                  goal: Ship the auth revamp
                  id: 9
                  issue_count: 15
                  name: Sprint 12
                  number: 12
                  project_id: 1
                  start_date: '2026-07-14'
                  status: active
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        end_date:
                          type: string
                        goal:
                          type: string
                        id:
                          type: integer
                        issue_count:
                          type: integer
                        name:
                          type: string
                        number:
                          type: integer
                        project_id:
                          type: integer
                        start_date:
                          type: string
                        status:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List sprints in a project.
      tags:
      - Issue Tracking
    post:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              end_date: '2026-07-28'
              goal: Ship the auth revamp
              name: Sprint 12
              start_date: '2026-07-14'
              status: planned
            schema:
              properties:
                end_date:
                  type: string
                goal:
                  type: string
                name:
                  type: string
                start_date:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-14T09:00:00Z'
                  end_date: '2026-07-28'
                  goal: Ship the auth revamp
                  id: 9
                  issue_count: 15
                  name: Sprint 12
                  number: 12
                  project_id: 1
                  start_date: '2026-07-14'
                  status: active
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      end_date:
                        type: string
                      goal:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      name:
                        type: string
                      number:
                        type: integer
                      project_id:
                        type: integer
                      start_date:
                        type: string
                      status:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a sprint.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/sprints/{sprint_id}:
    patch:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: path
        name: sprint_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: Sprint 12
              status: active
            schema:
              properties:
                name:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-14T09:00:00Z'
                  end_date: '2026-07-28'
                  goal: Ship the auth revamp
                  id: 9
                  issue_count: 15
                  name: Sprint 12
                  number: 12
                  project_id: 1
                  start_date: '2026-07-14'
                  status: active
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      end_date:
                        type: string
                      goal:
                        type: string
                      id:
                        type: integer
                      issue_count:
                        type: integer
                      name:
                        type: string
                      number:
                        type: integer
                      project_id:
                        type: integer
                      start_date:
                        type: string
                      status:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a sprint.
      tags:
      - Issue Tracking
  /editions/projects/{proj_key}/statuses:
    get:
      parameters:
      - in: path
        name: proj_key
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - category: started
                  color: '#f59e0b'
                  id: 5
                  is_terminal: false
                  name: In Progress
                  position: 2
                  workflow_id: 2
              schema:
                properties:
                  data:
                    items:
                      properties:
                        category:
                          type: string
                        color:
                          type: string
                        id:
                          type: integer
                        is_terminal:
                          type: boolean
                        name:
                          type: string
                        position:
                          type: integer
                        workflow_id:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List workflow statuses for a project.
      tags:
      - Issue Tracking
  /editions/search:
    get:
      description: "Query params: q (required), project_key, status_id, priority,\n\
        \              issue_type, assignee_id, page, per_page"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - assignee:
                    id: 7
                    name: Ada Lovelace
                  comment_count: 4
                  created_at: '2026-07-10T08:00:00Z'
                  created_by:
                    id: 7
                    name: Ada Lovelace
                  due_date: '2026-07-20'
                  epic_id: 3
                  estimate: 3
                  id: 101
                  identifier: ENG-14
                  is_archived: false
                  issue_type: bug
                  labels:
                  - color: '#6b7280'
                    id: 3
                    name: backend
                    project_id: 1
                  milestone_id: 2
                  number: 14
                  parent_id: null
                  priority: high
                  project_id: 1
                  project_key: ENG
                  resolved_at: null
                  status:
                    category: started
                    color: '#f59e0b'
                    id: 5
                    is_terminal: false
                    name: In Progress
                    position: 2
                    workflow_id: 2
                  title: Fix login redirect
                  updated_at: '2026-07-15T11:00:00Z'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        assignee:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        comment_count:
                          type: integer
                        created_at:
                          type: string
                        created_by:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                        due_date:
                          type: string
                        epic_id:
                          type: integer
                        estimate:
                          type: integer
                        id:
                          type: integer
                        identifier:
                          type: string
                        is_archived:
                          type: boolean
                        issue_type:
                          type: string
                        labels:
                          items:
                            properties:
                              color:
                                type: string
                              id:
                                type: integer
                              name:
                                type: string
                              project_id:
                                type: integer
                            type: object
                          type: array
                        milestone_id:
                          type: integer
                        number:
                          type: integer
                        parent_id:
                          nullable: true
                        priority:
                          type: string
                        project_id:
                          type: integer
                        project_key:
                          type: string
                        resolved_at:
                          nullable: true
                        status:
                          properties:
                            category:
                              type: string
                            color:
                              type: string
                            id:
                              type: integer
                            is_terminal:
                              type: boolean
                            name:
                              type: string
                            position:
                              type: integer
                            workflow_id:
                              type: integer
                          type: object
                        title:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Cross-project edition search.
      tags:
      - Issue Tracking
  /engage/devices:
    post:
      description: 'Creates a push channel identity for the contact so campaigns/journeys
        can

        reach them on mobile. Safe to call repeatedly with the same token.'
      requestBody:
        content:
          application/json:
            example:
              email: contact_example@example.com
              platform: ios
              token: fcm_or_apns_device_token
            schema:
              properties:
                email:
                  type: string
                platform:
                  type: string
                token:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  channel: push
                  platform: ios
                  status: active
                  uid: id-uuid
              schema:
                properties:
                  data:
                    properties:
                      channel:
                        type: string
                      platform:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Register (or refresh) a contact's mobile-push device token.
      tags:
      - Engage
  /engage/devices/{token}:
    delete:
      parameters:
      - in: path
        name: token
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ok: true
              schema:
                properties:
                  data:
                    properties:
                      ok:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Revoke a mobile-push device token (e.g. on logout / uninstall).
      tags:
      - Engage
  /engage/identities:
    post:
      description: 'Set ``status`` to ``unsubscribed`` to opt the contact out of that
        channel —

        the consent gate then blocks future marketing sends on it.'
      requestBody:
        content:
          application/json:
            example:
              channel: email
              email: contact_example@example.com
              status: active
            schema:
              properties:
                channel:
                  type: string
                email:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  channel: email
                  status: active
                  uid: id-uuid
              schema:
                properties:
                  data:
                    properties:
                      channel:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Register or update a contact's channel identity (opt-in / opt-out).
      tags:
      - Engage
  /engage/messages:
    post:
      description: 'Resolves (or creates) the canonical contact by email. The response
        reports

        the resulting status — ``sent``, or ``skipped`` with a ``skip_reason`` such

        as ``suppressed`` / ``frequency_capped`` / ``mau_limit`` when a rule blocked
        it.'
      requestBody:
        content:
          application/json:
            example:
              body: <p>Hi there</p>
              category: marketing
              channel: email
              email: contact_example@example.com
              subject: Welcome!
            schema:
              properties:
                body:
                  type: string
                category:
                  type: string
                channel:
                  type: string
                email:
                  type: string
                subject:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  channel: email
                  created_at: '2026-07-18T12:00:00+00:00'
                  skip_reason: null
                  status: sent
                  to_address: contact_example@example.com
                  uid: b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    properties:
                      channel:
                        type: string
                      created_at:
                        type: string
                      skip_reason:
                        nullable: true
                      status:
                        type: string
                      to_address:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Send a message to a contact through the full consent-gated send path.
      tags:
      - Engage
  /engage/outcomes:
    post:
      description: 'Feeds outcome/conversion reporting — attribute revenue or a goal
        completion

        back to the message (and its campaign/journey) that drove it.'
      requestBody:
        content:
          application/json:
            example:
              message_uid: b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e
              outcome_key: purchase
              value: 49
            schema:
              properties:
                message_uid:
                  type: string
                outcome_key:
                  type: string
                value:
                  type: number
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  message_uid: b2c3...
                  ok: true
                  outcome_key: purchase
              schema:
                properties:
                  data:
                    properties:
                      message_uid:
                        type: string
                      ok:
                        type: boolean
                      outcome_key:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Record a conversion/outcome attributed to an Engage message.
      tags:
      - Engage
  /engage/segments:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  segments:
                  - contact_count: 42
                    created_at: '2026-07-18T12:00:00+00:00'
                    description: Every contact with an email address.
                    kind: dynamic
                    name: All email contacts
                    rule_count: 1
                    uid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      segments:
                        items:
                          properties:
                            contact_count:
                              type: integer
                            created_at:
                              type: string
                            description:
                              type: string
                            kind:
                              type: string
                            name:
                              type: string
                            rule_count:
                              type: integer
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List Engage segments for the tenant.
      tags:
      - Engage
  /engage/segments/{uid}:
    get:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  contact_count: 42
                  created_at: '2026-07-18T12:00:00+00:00'
                  description: Every contact with an email address.
                  kind: dynamic
                  name: All email contacts
                  rule_count: 1
                  uid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      contact_count:
                        type: integer
                      created_at:
                        type: string
                      description:
                        type: string
                      kind:
                        type: string
                      name:
                        type: string
                      rule_count:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get one Engage segment, including its live contact count.
      tags:
      - Engage
  /file-requests:
    get:
      description: Returns a paginated list of file requests for this account. Filter
        by `?status=open|closed|expired`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - open
          - closed
          - expired
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/FileRequest'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List file requests
      tags:
      - File Transfer & Requests
    post:
      description: Create a new file request and get a shareable upload link. Share
        the `upload_url` with anyone — no account needed on their end.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileRequestInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileRequest'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create file request
      tags:
      - File Transfer & Requests
  /file-requests/{request_id}:
    delete:
      description: Close a file request so no more uploads can be submitted. Pass
        `?permanent=true` to delete the request and all submitted files.
      parameters:
      - in: path
        name: request_id
        required: true
        schema:
          type: integer
      - description: If true, permanently delete the request and all submitted files.
        in: query
        name: permanent
        schema:
          default: false
          type: boolean
      responses:
        '200':
          description: Closed or deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Close file request
      tags:
      - File Transfer & Requests
    get:
      description: Retrieve a single file request by ID, including all submissions
        and uploaded files.
      parameters:
      - in: path
        name: request_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/FileRequest'
                    - properties:
                        submissions:
                          items:
                            $ref: '#/components/schemas/FileRequestSubmission'
                          type: array
                      type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get file request
      tags:
      - File Transfer & Requests
  /file-requests/{request_id}/submissions:
    get:
      description: Returns all submissions for a file request, including files in
        each submission.
      parameters:
      - in: path
        name: request_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/FileRequestSubmission'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List submissions
      tags:
      - File Transfer & Requests
  /helpcenter:
    get:
      description: Returns configuration and stats for this account's Help Center.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get Help Center
      tags:
      - Help Center
  /helpcenter/articles:
    get:
      description: Returns paginated Help Center articles. Filter by `?status=draft|published`
        or `?category_id=<id>`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - published
          type: string
      - in: query
        name: category_id
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/HelpArticle'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List articles
      tags:
      - Help Center
    post:
      description: Create a new Help Center article. Body is HTML.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HelpArticleInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/HelpArticle'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create article
      tags:
      - Help Center
  /helpcenter/articles/{article_id}:
    delete:
      description: Permanently delete a Help Center article.
      parameters:
      - in: path
        name: article_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete article
      tags:
      - Help Center
    get:
      description: Get a single article by ID. Includes full HTML body.
      parameters:
      - in: path
        name: article_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/HelpArticle'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get article
      tags:
      - Help Center
    patch:
      description: Update article fields. Pass only fields to change.
      parameters:
      - in: path
        name: article_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HelpArticleInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/HelpArticle'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update article
      tags:
      - Help Center
  /helpcenter/categories:
    get:
      description: Returns all Help Center categories.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/HelpCategory'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List categories
      tags:
      - Help Center
    post:
      description: Create a new Help Center category.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                color:
                  default: '#3b82f6'
                  type: string
                description:
                  type: string
                icon:
                  default: bi-folder
                  type: string
                is_published:
                  default: true
                  type: boolean
                title:
                  type: string
              required:
              - title
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/HelpCategory'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create category
      tags:
      - Help Center
  /landing-pages:
    get:
      description: "Query params:\n  status — 'published' | 'draft' (omit for all)\n\
        \  limit  — max results (default 50)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - accent_color: '#4f46e5'
                  background_color: '#ffffff'
                  body_text: Sign up today.
                  conversion_count: 220
                  conversion_rate: 14.7
                  created_at: '2026-06-01T09:00:00+00:00'
                  cta_text: Get Started
                  custom_domain: null
                  custom_domain_verified: false
                  form_fields:
                  - enabled: true
                    key: email
                    label: Email Address
                    required: true
                    type: email
                  headline: Start your free trial
                  id: 1
                  logo_url: https://cdn.totalctrl.app/logo.png
                  meta_description: Sign up for a free trial.
                  meta_title: Free Trial
                  public_url: https://acme.totalctrl.app/lp/acme/free-trial
                  published_at: '2026-07-01T12:00:00+00:00'
                  redirect_url: ''
                  slug: free-trial
                  status: published
                  subheadline: No credit card required
                  text_color: '#111827'
                  thank_you_message: We'll be in touch soon.
                  thank_you_title: Thank you!
                  title: Free Trial
                  uid: b7e6a1d2-9c3f-4a8b-8e2d-1f0c5a6b7c8d
                  updated_at: '2026-07-10T14:30:00+00:00'
                  view_count: 1500
              schema:
                properties:
                  data:
                    items:
                      properties:
                        accent_color:
                          type: string
                        background_color:
                          type: string
                        body_text:
                          type: string
                        conversion_count:
                          type: integer
                        conversion_rate:
                          type: number
                        created_at:
                          type: string
                        cta_text:
                          type: string
                        custom_domain:
                          nullable: true
                        custom_domain_verified:
                          type: boolean
                        form_fields:
                          items:
                            properties:
                              enabled:
                                type: boolean
                              key:
                                type: string
                              label:
                                type: string
                              required:
                                type: boolean
                              type:
                                type: string
                            type: object
                          type: array
                        headline:
                          type: string
                        id:
                          type: integer
                        logo_url:
                          type: string
                        meta_description:
                          type: string
                        meta_title:
                          type: string
                        public_url:
                          type: string
                        published_at:
                          type: string
                        redirect_url:
                          type: string
                        slug:
                          type: string
                        status:
                          type: string
                        subheadline:
                          type: string
                        text_color:
                          type: string
                        thank_you_message:
                          type: string
                        thank_you_title:
                          type: string
                        title:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                        view_count:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List landing pages.
      tags:
      - Landing Pages
    post:
      description: "Required: title\nOptional: headline, subheadline, body_text, cta_text,\
        \ slug,\n          background_color, accent_color, text_color, logo_url,\n\
        \          thank_you_title, thank_you_message, redirect_url,\n          meta_title,\
        \ meta_description"
      requestBody:
        content:
          application/json:
            example:
              accent_color: '#4f46e5'
              background_color: '#ffffff'
              body_text: Sign up today.
              cta_text: Get Started
              headline: Start your free trial
              logo_url: https://cdn.totalctrl.app/logo.png
              meta_description: Sign up for a free trial.
              meta_title: Free Trial
              redirect_url: ''
              slug: free-trial
              subheadline: No credit card required
              text_color: '#111827'
              thank_you_message: We'll be in touch soon.
              thank_you_title: Thank you!
              title: Free Trial
            schema:
              properties:
                accent_color:
                  type: string
                background_color:
                  type: string
                body_text:
                  type: string
                cta_text:
                  type: string
                headline:
                  type: string
                logo_url:
                  type: string
                meta_description:
                  type: string
                meta_title:
                  type: string
                redirect_url:
                  type: string
                slug:
                  type: string
                subheadline:
                  type: string
                text_color:
                  type: string
                thank_you_message:
                  type: string
                thank_you_title:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  accent_color: '#4f46e5'
                  background_color: '#ffffff'
                  body_text: Sign up today.
                  conversion_count: 220
                  conversion_rate: 14.7
                  created_at: '2026-06-01T09:00:00+00:00'
                  cta_text: Get Started
                  custom_domain: null
                  custom_domain_verified: false
                  form_fields:
                  - enabled: true
                    key: email
                    label: Email Address
                    required: true
                    type: email
                  headline: Start your free trial
                  id: 1
                  logo_url: https://cdn.totalctrl.app/logo.png
                  meta_description: Sign up for a free trial.
                  meta_title: Free Trial
                  public_url: https://acme.totalctrl.app/lp/acme/free-trial
                  published_at: '2026-07-01T12:00:00+00:00'
                  redirect_url: ''
                  slug: free-trial
                  status: published
                  subheadline: No credit card required
                  text_color: '#111827'
                  thank_you_message: We'll be in touch soon.
                  thank_you_title: Thank you!
                  title: Free Trial
                  uid: b7e6a1d2-9c3f-4a8b-8e2d-1f0c5a6b7c8d
                  updated_at: '2026-07-10T14:30:00+00:00'
                  view_count: 1500
              schema:
                properties:
                  data:
                    properties:
                      accent_color:
                        type: string
                      background_color:
                        type: string
                      body_text:
                        type: string
                      conversion_count:
                        type: integer
                      conversion_rate:
                        type: number
                      created_at:
                        type: string
                      cta_text:
                        type: string
                      custom_domain:
                        nullable: true
                      custom_domain_verified:
                        type: boolean
                      form_fields:
                        items:
                          properties:
                            enabled:
                              type: boolean
                            key:
                              type: string
                            label:
                              type: string
                            required:
                              type: boolean
                            type:
                              type: string
                          type: object
                        type: array
                      headline:
                        type: string
                      id:
                        type: integer
                      logo_url:
                        type: string
                      meta_description:
                        type: string
                      meta_title:
                        type: string
                      public_url:
                        type: string
                      published_at:
                        type: string
                      redirect_url:
                        type: string
                      slug:
                        type: string
                      status:
                        type: string
                      subheadline:
                        type: string
                      text_color:
                        type: string
                      thank_you_message:
                        type: string
                      thank_you_title:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new landing page (draft).
      tags:
      - Landing Pages
  /landing-pages/{page_id}:
    delete:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a landing page and all its submissions.
      tags:
      - Landing Pages
    get:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  accent_color: '#4f46e5'
                  background_color: '#ffffff'
                  body_text: Sign up today.
                  conversion_count: 220
                  conversion_rate: 14.7
                  created_at: '2026-06-01T09:00:00+00:00'
                  cta_text: Get Started
                  custom_domain: null
                  custom_domain_verified: false
                  form_fields:
                  - enabled: true
                    key: email
                    label: Email Address
                    required: true
                    type: email
                  headline: Start your free trial
                  id: 1
                  logo_url: https://cdn.totalctrl.app/logo.png
                  meta_description: Sign up for a free trial.
                  meta_title: Free Trial
                  public_url: https://acme.totalctrl.app/lp/acme/free-trial
                  published_at: '2026-07-01T12:00:00+00:00'
                  redirect_url: ''
                  slug: free-trial
                  status: published
                  subheadline: No credit card required
                  text_color: '#111827'
                  thank_you_message: We'll be in touch soon.
                  thank_you_title: Thank you!
                  title: Free Trial
                  uid: b7e6a1d2-9c3f-4a8b-8e2d-1f0c5a6b7c8d
                  updated_at: '2026-07-10T14:30:00+00:00'
                  view_count: 1500
              schema:
                properties:
                  data:
                    properties:
                      accent_color:
                        type: string
                      background_color:
                        type: string
                      body_text:
                        type: string
                      conversion_count:
                        type: integer
                      conversion_rate:
                        type: number
                      created_at:
                        type: string
                      cta_text:
                        type: string
                      custom_domain:
                        nullable: true
                      custom_domain_verified:
                        type: boolean
                      form_fields:
                        items:
                          properties:
                            enabled:
                              type: boolean
                            key:
                              type: string
                            label:
                              type: string
                            required:
                              type: boolean
                            type:
                              type: string
                          type: object
                        type: array
                      headline:
                        type: string
                      id:
                        type: integer
                      logo_url:
                        type: string
                      meta_description:
                        type: string
                      meta_title:
                        type: string
                      public_url:
                        type: string
                      published_at:
                        type: string
                      redirect_url:
                        type: string
                      slug:
                        type: string
                      status:
                        type: string
                      subheadline:
                        type: string
                      text_color:
                        type: string
                      thank_you_message:
                        type: string
                      thank_you_title:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single landing page by ID.
      tags:
      - Landing Pages
    patch:
      description: 'Any field from the create endpoint is patchable.

        Set status to ''published'' to publish (or ''draft'' to unpublish).'
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              headline: Start your free trial
              status: published
              title: Free Trial
            schema:
              properties:
                headline:
                  type: string
                status:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  accent_color: '#4f46e5'
                  background_color: '#ffffff'
                  body_text: Sign up today.
                  conversion_count: 220
                  conversion_rate: 14.7
                  created_at: '2026-06-01T09:00:00+00:00'
                  cta_text: Get Started
                  custom_domain: null
                  custom_domain_verified: false
                  form_fields:
                  - enabled: true
                    key: email
                    label: Email Address
                    required: true
                    type: email
                  headline: Start your free trial
                  id: 1
                  logo_url: https://cdn.totalctrl.app/logo.png
                  meta_description: Sign up for a free trial.
                  meta_title: Free Trial
                  public_url: https://acme.totalctrl.app/lp/acme/free-trial
                  published_at: '2026-07-01T12:00:00+00:00'
                  redirect_url: ''
                  slug: free-trial
                  status: published
                  subheadline: No credit card required
                  text_color: '#111827'
                  thank_you_message: We'll be in touch soon.
                  thank_you_title: Thank you!
                  title: Free Trial
                  uid: b7e6a1d2-9c3f-4a8b-8e2d-1f0c5a6b7c8d
                  updated_at: '2026-07-10T14:30:00+00:00'
                  view_count: 1500
              schema:
                properties:
                  data:
                    properties:
                      accent_color:
                        type: string
                      background_color:
                        type: string
                      body_text:
                        type: string
                      conversion_count:
                        type: integer
                      conversion_rate:
                        type: number
                      created_at:
                        type: string
                      cta_text:
                        type: string
                      custom_domain:
                        nullable: true
                      custom_domain_verified:
                        type: boolean
                      form_fields:
                        items:
                          properties:
                            enabled:
                              type: boolean
                            key:
                              type: string
                            label:
                              type: string
                            required:
                              type: boolean
                            type:
                              type: string
                          type: object
                        type: array
                      headline:
                        type: string
                      id:
                        type: integer
                      logo_url:
                        type: string
                      meta_description:
                        type: string
                      meta_title:
                        type: string
                      public_url:
                        type: string
                      published_at:
                        type: string
                      redirect_url:
                        type: string
                      slug:
                        type: string
                      status:
                        type: string
                      subheadline:
                        type: string
                      text_color:
                        type: string
                      thank_you_message:
                        type: string
                      thank_you_title:
                        type: string
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a landing page.
      tags:
      - Landing Pages
  /landing-pages/{page_id}/submissions:
    get:
      description: "Query params:\n  limit  — max results (default 50, max 200)\n\
        \  offset — pagination offset"
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  limit: 50
                  offset: 0
                  page_id: 1
                  submissions:
                  - crm_contact_id: 88
                    data:
                      company: Beta LLC
                    email: lead@example.com
                    first_name: Sam
                    full_name: Sam Lee
                    id: 1
                    last_name: Lee
                    submitted_at: '2026-07-10T14:30:00+00:00'
                  total: 220
              schema:
                properties:
                  data:
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      page_id:
                        type: integer
                      submissions:
                        items:
                          properties:
                            crm_contact_id:
                              type: integer
                            data:
                              properties:
                                company:
                                  type: string
                              type: object
                            email:
                              type: string
                            first_name:
                              type: string
                            full_name:
                              type: string
                            id:
                              type: integer
                            last_name:
                              type: string
                            submitted_at:
                              type: string
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List form submissions for a landing page.
      tags:
      - Landing Pages
  /newsletter/newsletters:
    get:
      description: Returns all newsletters for this account.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Newsletter'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List newsletters
      tags:
      - Newsletter
  /newsletter/newsletters/{nl_uuid}:
    get:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  newsletter:
                    accent_color: '#4f46e5'
                    created_at: '2026-01-15T09:30:00+00:00'
                    description: Monthly product news and tips
                    double_optin: true
                    from_email: news@acme.com
                    from_name: Acme Team
                    is_active: true
                    issue_count: 24
                    name: Product Updates
                    reply_to: support@acme.com
                    slug: product-updates
                    subscriber_count: 1280
                    uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              schema:
                properties:
                  data:
                    properties:
                      newsletter:
                        properties:
                          accent_color:
                            type: string
                          created_at:
                            type: string
                          description:
                            type: string
                          double_optin:
                            type: boolean
                          from_email:
                            type: string
                          from_name:
                            type: string
                          is_active:
                            type: boolean
                          issue_count:
                            type: integer
                          name:
                            type: string
                          reply_to:
                            type: string
                          slug:
                            type: string
                          subscriber_count:
                            type: integer
                          uuid:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get newsletter newsletters nl_uuid
      tags:
      - Newsletter
  /newsletter/newsletters/{nl_uuid}/analytics:
    get:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  active_subscribers: 1280
                  avg_click_rate: 10.2
                  avg_open_rate: 44.5
                  issues_sent: 24
                  newsletter_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  total_emails_sent: 28800
                  total_subscribers: 1400
              schema:
                properties:
                  data:
                    properties:
                      active_subscribers:
                        type: integer
                      avg_click_rate:
                        type: number
                      avg_open_rate:
                        type: number
                      issues_sent:
                        type: integer
                      newsletter_uuid:
                        type: string
                      total_emails_sent:
                        type: integer
                      total_subscribers:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get newsletter newsletters nl_uuid analytics
      tags:
      - Newsletter
  /newsletter/newsletters/{nl_uuid}/editions:
    get:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  editions:
                  - click_rate: 11.14
                    clicked_count: 132
                    complained_count: 1
                    created_at: '2026-06-14T16:20:00+00:00'
                    delivered_count: 1185
                    is_web_published: true
                    open_rate: 45.57
                    opened_count: 540
                    preview_text: This month in review
                    recipient_count: 1200
                    scheduled_at: '2026-06-15T08:00:00+00:00'
                    sent_at: '2026-06-15T08:01:00+00:00'
                    status: sent
                    subject: June Newsletter
                    unsubscribed_count: 8
                    uuid: c3d4e5f6-a7b8-9012-cdef-345678901234
              schema:
                properties:
                  data:
                    properties:
                      editions:
                        items:
                          properties:
                            click_rate:
                              type: number
                            clicked_count:
                              type: integer
                            complained_count:
                              type: integer
                            created_at:
                              type: string
                            delivered_count:
                              type: integer
                            is_web_published:
                              type: boolean
                            open_rate:
                              type: number
                            opened_count:
                              type: integer
                            preview_text:
                              type: string
                            recipient_count:
                              type: integer
                            scheduled_at:
                              type: string
                            sent_at:
                              type: string
                            status:
                              type: string
                            subject:
                              type: string
                            unsubscribed_count:
                              type: integer
                            uuid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get newsletter newsletters nl_uuid editions
      tags:
      - Newsletter
  /newsletter/newsletters/{nl_uuid}/editions/{edition_uuid}:
    get:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      - in: path
        name: edition_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  edition:
                    click_rate: 11.14
                    clicked_count: 132
                    complained_count: 1
                    content_html: <h1>June Newsletter</h1><p>This month in review...</p>
                    created_at: '2026-06-14T16:20:00+00:00'
                    delivered_count: 1185
                    is_web_published: true
                    open_rate: 45.57
                    opened_count: 540
                    preview_text: This month in review
                    recipient_count: 1200
                    scheduled_at: '2026-06-15T08:00:00+00:00'
                    sent_at: '2026-06-15T08:01:00+00:00'
                    status: sent
                    subject: June Newsletter
                    unsubscribed_count: 8
                    uuid: c3d4e5f6-a7b8-9012-cdef-345678901234
              schema:
                properties:
                  data:
                    properties:
                      edition:
                        properties:
                          click_rate:
                            type: number
                          clicked_count:
                            type: integer
                          complained_count:
                            type: integer
                          content_html:
                            type: string
                          created_at:
                            type: string
                          delivered_count:
                            type: integer
                          is_web_published:
                            type: boolean
                          open_rate:
                            type: number
                          opened_count:
                            type: integer
                          preview_text:
                            type: string
                          recipient_count:
                            type: integer
                          scheduled_at:
                            type: string
                          sent_at:
                            type: string
                          status:
                            type: string
                          subject:
                            type: string
                          unsubscribed_count:
                            type: integer
                          uuid:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get newsletter newsletters nl_uuid editions edition_uuid
      tags:
      - Newsletter
  /newsletter/newsletters/{nl_uuid}/subscribers:
    get:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  limit: 50
                  page: 1
                  subscribers:
                  - confirmed_at: '2026-06-01T12:05:00+00:00'
                    email: jane@example.com
                    first_name: Jane
                    last_name: Doe
                    source: api
                    status: active
                    subscribed_at: '2026-06-01T12:00:00+00:00'
                    unsubbed_at: null
                    uuid: b2c3d4e5-f6a7-8901-bcde-f23456789012
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      limit:
                        type: integer
                      page:
                        type: integer
                      subscribers:
                        items:
                          properties:
                            confirmed_at:
                              type: string
                            email:
                              type: string
                            first_name:
                              type: string
                            last_name:
                              type: string
                            source:
                              type: string
                            status:
                              type: string
                            subscribed_at:
                              type: string
                            unsubbed_at:
                              nullable: true
                            uuid:
                              type: string
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get newsletter newsletters nl_uuid subscribers
      tags:
      - Newsletter
    post:
      parameters:
      - in: path
        name: nl_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: jane@example.com
              first_name: Jane
              last_name: Doe
            schema:
              properties:
                email:
                  type: string
                first_name:
                  type: string
                last_name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  subscriber:
                    confirmed_at: '2026-06-01T12:05:00+00:00'
                    email: jane@example.com
                    first_name: Jane
                    last_name: Doe
                    source: api
                    status: active
                    subscribed_at: '2026-06-01T12:00:00+00:00'
                    unsubbed_at: null
                    uuid: b2c3d4e5-f6a7-8901-bcde-f23456789012
              schema:
                properties:
                  data:
                    properties:
                      subscriber:
                        properties:
                          confirmed_at:
                            type: string
                          email:
                            type: string
                          first_name:
                            type: string
                          last_name:
                            type: string
                          source:
                            type: string
                          status:
                            type: string
                          subscribed_at:
                            type: string
                          unsubbed_at:
                            nullable: true
                          uuid:
                            type: string
                        type: object
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create newsletter newsletters nl_uuid subscribers
      tags:
      - Newsletter
  /note-tags:
    get:
      description: Returns all note tags for this account, sorted alphabetically.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/NoteTag'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List note tags
      tags:
      - Notes
    post:
      description: Create a new tag. Tag names are unique per account.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteTagInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/NoteTag'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create note tag
      tags:
      - Notes
  /note-tags/{tag_id}:
    delete:
      description: Delete a tag. It is removed from all notes automatically.
      parameters:
      - in: path
        name: tag_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete note tag
      tags:
      - Notes
    patch:
      description: Rename a tag or change its color.
      parameters:
      - in: path
        name: tag_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteTagInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/NoteTag'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update note tag
      tags:
      - Notes
  /notebooks:
    get:
      description: Returns all notebooks for this account.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Notebook'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List notebooks
      tags:
      - Notes
    post:
      description: Create a new notebook.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotebookInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Notebook'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create notebook
      tags:
      - Notes
  /notebooks/{notebook_uid}:
    delete:
      parameters:
      - in: path
        name: notebook_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: nb_7f3a2c9e
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a notebook (notes moved to default notebook).
      tags:
      - Notes
    patch:
      parameters:
      - in: path
        name: notebook_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              color: '#3b82f6'
              icon: bi-journal
              title: Personal
            schema:
              properties:
                color:
                  type: string
                icon:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#3b82f6'
                  icon: bi-journal
                  id: nb_7f3a2c9e
                  is_default: false
                  note_count: 12
                  order: 1
                  title: Personal
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_default:
                        type: boolean
                      note_count:
                        type: integer
                      order:
                        type: integer
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a notebook.
      tags:
      - Notes
  /notes:
    get:
      description: Returns paginated notes. Filter by `?notebook_id=`, `?tag_id=`,
        `?is_pinned=true`, `?is_trashed=true`, or `?search=<text>`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: notebook_id
        schema:
          type: integer
      - in: query
        name: tag_id
        schema:
          type: integer
      - in: query
        name: is_pinned
        schema:
          type: boolean
      - in: query
        name: is_trashed
        schema:
          default: false
          type: boolean
      - in: query
        name: search
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Note'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List notes
      tags:
      - Notes
    post:
      description: Create a new note. Defaults to the account's default notebook if
        `notebook_id` is omitted.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Note'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create note
      tags:
      - Notes
  /notes/{note_id}:
    delete:
      description: Soft-deletes (trashes) the note by default. Pass `?permanent=true`
        to permanently delete it.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      - in: query
        name: permanent
        schema:
          default: false
          type: boolean
      responses:
        '200':
          description: Trashed or deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trash or delete note
      tags:
      - Notes
    get:
      description: Fetch a single note including full Quill Delta `content`.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Note'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get note
      tags:
      - Notes
    patch:
      description: Update title, content, color, pin status, notebook, or tags.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Note'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update note
      tags:
      - Notes
  /notes/{note_id}/restore:
    post:
      description: Restore a trashed note back to its notebook.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Note'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Restore note
      tags:
      - Notes
  /notes/{note_id}/shares:
    get:
      description: Returns all users the note is shared with.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/NoteShare'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List note shares
      tags:
      - Notes
    post:
      description: Share a note with a teammate. If already shared, updates the permission.
        Permission is `view` (read-only) or `edit`.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteShareInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/NoteShare'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Share note
      tags:
      - Notes
  /notes/{note_id}/shares/{user_id}:
    delete:
      description: Remove a user's access to a shared note.
      parameters:
      - in: path
        name: note_id
        required: true
        schema:
          type: integer
      - in: path
        name: user_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Share removed
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Remove share
      tags:
      - Notes
  /orchestration/executions/{execution_id}:
    get:
      parameters:
      - in: path
        name: execution_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  duration_ms: 1840
                  error_message: null
                  finished_at: '2026-07-17T12:00:02+00:00'
                  id: 5501
                  started_at: '2026-07-17T12:00:00+00:00'
                  status: success
                  step_results:
                  - action_id: send_message
                    app_id: slack
                    error: null
                    output:
                      ok: true
                    status: success
                    step_id: step_2
                    type: action
                  trigger_data:
                    email: jordan@acme.com
                    name: Jordan Lee
                  workflow_id: 17
              schema:
                properties:
                  data:
                    properties:
                      duration_ms:
                        type: integer
                      error_message:
                        nullable: true
                      finished_at:
                        type: string
                      id:
                        type: integer
                      started_at:
                        type: string
                      status:
                        type: string
                      step_results:
                        items:
                          properties:
                            action_id:
                              type: string
                            app_id:
                              type: string
                            error:
                              nullable: true
                            output:
                              properties:
                                ok:
                                  type: boolean
                              type: object
                            status:
                              type: string
                            step_id:
                              type: string
                            type:
                              type: string
                          type: object
                        type: array
                      trigger_data:
                        properties:
                          email:
                            type: string
                          name:
                            type: string
                        type: object
                      workflow_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: A single run's status and per-step results.
      tags:
      - Orchestration
  /orchestration/workflows:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  workflows:
                  - created_at: '2026-07-01T09:00:00+00:00'
                    description: 'Notify #sales whenever a contact is created'
                    id: 17
                    is_active: true
                    is_configured: true
                    last_run_at: '2026-07-17T12:00:00+00:00'
                    name: New signup → Slack
                    run_count: 42
                    updated_at: '2026-07-17T12:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      workflows:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            id:
                              type: integer
                            is_active:
                              type: boolean
                            is_configured:
                              type: boolean
                            last_run_at:
                              type: string
                            name:
                              type: string
                            run_count:
                              type: integer
                            updated_at:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'List workflows. Query: ?active=true to only return active ones.'
      tags:
      - Orchestration
  /orchestration/workflows/{workflow_id}:
    get:
      parameters:
      - in: path
        name: workflow_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:00:00+00:00'
                  description: 'Notify #sales whenever a contact is created'
                  id: 17
                  is_active: true
                  is_configured: true
                  last_run_at: '2026-07-17T12:00:00+00:00'
                  name: New signup → Slack
                  run_count: 42
                  steps:
                  - action_id: contact.created
                    app_id: totalctrl
                    type: trigger
                  - action_id: send_message
                    app_id: slack
                    type: action
                  updated_at: '2026-07-17T12:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      id:
                        type: integer
                      is_active:
                        type: boolean
                      is_configured:
                        type: boolean
                      last_run_at:
                        type: string
                      name:
                        type: string
                      run_count:
                        type: integer
                      steps:
                        items:
                          properties:
                            action_id:
                              type: string
                            app_id:
                              type: string
                            type:
                              type: string
                          type: object
                        type: array
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Workflow detail, including a compact step summary.
      tags:
      - Orchestration
  /orchestration/workflows/{workflow_id}/executions:
    get:
      parameters:
      - in: path
        name: workflow_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  executions:
                  - duration_ms: 1840
                    finished_at: '2026-07-17T12:00:02+00:00'
                    id: 5501
                    started_at: '2026-07-17T12:00:00+00:00'
                    status: success
                    workflow_id: 17
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      executions:
                        items:
                          properties:
                            duration_ms:
                              type: integer
                            finished_at:
                              type: string
                            id:
                              type: integer
                            started_at:
                              type: string
                            status:
                              type: string
                            workflow_id:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Recent runs of a workflow (newest first). Query: ?limit= (default
        20, max 100).'
      tags:
      - Orchestration
  /orchestration/workflows/{workflow_id}/run:
    post:
      description: 'the trigger data). Returns the resulting execution, including
        per-step

        results. Body: any JSON object (optional).'
      parameters:
      - in: path
        name: workflow_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: jordan@acme.com
              name: Jordan Lee
              plan: pro
            schema:
              properties:
                email:
                  type: string
                name:
                  type: string
                plan:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  duration_ms: 1840
                  finished_at: '2026-07-17T12:00:02+00:00'
                  id: 5501
                  started_at: '2026-07-17T12:00:00+00:00'
                  status: success
                  step_results:
                  - action_id: send_message
                    app_id: slack
                    error: null
                    output:
                      ok: true
                    status: success
                    step_id: step_2
                    type: action
                  workflow_id: 17
              schema:
                properties:
                  data:
                    properties:
                      duration_ms:
                        type: integer
                      finished_at:
                        type: string
                      id:
                        type: integer
                      started_at:
                        type: string
                      status:
                        type: string
                      step_results:
                        items:
                          properties:
                            action_id:
                              type: string
                            app_id:
                              type: string
                            error:
                              nullable: true
                            output:
                              properties:
                                ok:
                                  type: boolean
                              type: object
                            status:
                              type: string
                            step_id:
                              type: string
                            type:
                              type: string
                          type: object
                        type: array
                      workflow_id:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Run a workflow synchronously with a JSON payload (available to steps
        as
      tags:
      - Orchestration
  /orgcharts:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T09:30:00'
                  embed_enabled: true
                  id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
                  name: Leadership Chart
                  node_count: 12
                  updated_at: '2026-07-10T14:05:00'
                  visibility: org
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        embed_enabled:
                          type: boolean
                        id:
                          type: string
                        name:
                          type: string
                        node_count:
                          type: integer
                        updated_at:
                          type: string
                        visibility:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List org charts in the workspace (tenant-scoped — includes private
        ones).
      tags:
      - Org Charts
    post:
      requestBody:
        content:
          application/json:
            example:
              name: Leadership Chart
              visibility: org
            schema:
              properties:
                name:
                  type: string
                visibility:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:30:00'
                  embed_enabled: true
                  id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
                  name: Leadership Chart
                  node_count: 12
                  updated_at: '2026-07-10T14:05:00'
                  visibility: org
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      embed_enabled:
                        type: boolean
                      id:
                        type: string
                      name:
                        type: string
                      node_count:
                        type: integer
                      updated_at:
                        type: string
                      visibility:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Create an org chart. Body (JSON): { name (req), visibility (private|org)
        }.'
      tags:
      - Org Charts
  /orgcharts/nodes/{node_uid}:
    delete:
      parameters:
      - in: path
        name: node_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: ocn1a2b3-4c5d-6e7f-8091-0a2b3c4d5e60
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a node (its children re-parent per the DB cascade).
      tags:
      - Org Charts
    patch:
      description: is_new_hire?, first_name?, last_name? }. parent_uid="" detaches
        to top.
      parameters:
      - in: path
        name: node_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              first_name: Alex
              is_new_hire: false
              last_name: Rivera
              location: Remote - US
              parent_uid: ocn2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
              title: Staff Engineer
            schema:
              properties:
                first_name:
                  type: string
                is_new_hire:
                  type: boolean
                last_name:
                  type: string
                location:
                  type: string
                parent_uid:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  id: ocn1a2b3-4c5d-6e7f-8091-0a2b3c4d5e60
                  name: Alex Rivera
                  parent_id: ocn2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                  title: Staff Engineer
              schema:
                properties:
                  data:
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      parent_id:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Update a node. Body (JSON): { parent_uid?, title?, location?,'
      tags:
      - Org Charts
  /orgcharts/{chart_uid}:
    delete:
      parameters:
      - in: path
        name: chart_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an org chart and all its nodes.
      tags:
      - Org Charts
    get:
      parameters:
      - in: path
        name: chart_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  embed_enabled: true
                  id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
                  name: Leadership Chart
                  tree:
                    roots:
                    - avatar_uid: null
                      children: []
                      department: ''
                      email: ''
                      has_avatar: false
                      id: ocn1a2b3-4c5d-6e7f-8091-0a2b3c4d5e60
                      name: Dana Lee
                      new_hire: false
                      title: VP Engineering
                  visibility: org
              schema:
                properties:
                  data:
                    properties:
                      embed_enabled:
                        type: boolean
                      id:
                        type: string
                      name:
                        type: string
                      tree:
                        properties:
                          roots:
                            items:
                              properties:
                                avatar_uid:
                                  nullable: true
                                children:
                                  items: {}
                                  type: array
                                department:
                                  type: string
                                email:
                                  type: string
                                has_avatar:
                                  type: boolean
                                id:
                                  type: string
                                name:
                                  type: string
                                new_hire:
                                  type: boolean
                                title:
                                  type: string
                              type: object
                            type: array
                        type: object
                      visibility:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: An org chart with its full nested tree.
      tags:
      - Org Charts
    patch:
      parameters:
      - in: path
        name: chart_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              embed_enabled: true
              name: Leadership Chart
              visibility: org
            schema:
              properties:
                embed_enabled:
                  type: boolean
                name:
                  type: string
                visibility:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:30:00'
                  embed_enabled: true
                  id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
                  name: Leadership Chart
                  node_count: 12
                  updated_at: '2026-07-10T14:05:00'
                  visibility: org
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      embed_enabled:
                        type: boolean
                      id:
                        type: string
                      name:
                        type: string
                      node_count:
                        type: integer
                      updated_at:
                        type: string
                      visibility:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Update an org chart. Body (JSON): { name?, visibility?, embed_enabled?
        }.'
      tags:
      - Org Charts
  /orgcharts/{chart_uid}/nodes:
    post:
      description: 'workspace person, or { first_name, last_name, title?, location?,

        is_new_hire? } for a manual entry. Optional { parent_uid } to nest it.'
      parameters:
      - in: path
        name: chart_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              first_name: Alex
              is_new_hire: false
              last_name: Rivera
              location: Remote - US
              parent_uid: ocn2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
              title: Staff Engineer
              user_uid: u2b3c4d5-6e7f-8091-0a2b-3c4d5e6f7083
            schema:
              properties:
                first_name:
                  type: string
                is_new_hire:
                  type: boolean
                last_name:
                  type: string
                location:
                  type: string
                parent_uid:
                  type: string
                title:
                  type: string
                user_uid:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  chart_id: oc1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4051
                  id: ocn1a2b3-4c5d-6e7f-8091-0a2b3c4d5e60
                  name: Alex Rivera
                  parent_id: ocn2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                  title: Staff Engineer
              schema:
                properties:
                  data:
                    properties:
                      chart_id:
                        type: string
                      id:
                        type: string
                      name:
                        type: string
                      parent_id:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Add a node to a chart. Body (JSON): either { user_uid } to link a'
      tags:
      - Org Charts
  /pim/attributes:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - code: color
                  id: 3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f
                  is_localizable: false
                  labels:
                    en_US: Color
                  type: text
              schema:
                properties:
                  data:
                    items:
                      properties:
                        code:
                          type: string
                        id:
                          type: string
                        is_localizable:
                          type: boolean
                        labels:
                          properties:
                            en_US:
                              type: string
                          type: object
                        type:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List attribute definitions for the tenant.
      tags:
      - Product Information (PIM)
  /pim/categories:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - code: shoes
                  id: 4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f80
                  labels:
                    en_US: Shoes
                  parent_id: null
              schema:
                properties:
                  data:
                    items:
                      properties:
                        code:
                          type: string
                        id:
                          type: string
                        labels:
                          properties:
                            en_US:
                              type: string
                          type: object
                        parent_id:
                          nullable: true
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List categories for the tenant (ordered by tree left-index).
      tags:
      - Product Information (PIM)
  /pim/connectors/bigcommerce/sync:
    post:
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  errors:
                  - error: Rejected by remote API
                    sku: ACME-001
                  pushed: 42
                  total: 43
              schema:
                properties:
                  data:
                    properties:
                      errors:
                        items:
                          properties:
                            error:
                              type: string
                            sku:
                              type: string
                          type: object
                        type: array
                      pushed:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trigger a BigCommerce push.
      tags:
      - Product Information (PIM)
  /pim/connectors/magento/sync:
    post:
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  errors:
                  - error: Rejected by remote API
                    sku: ACME-001
                  pushed: 42
                  total: 43
              schema:
                properties:
                  data:
                    properties:
                      errors:
                        items:
                          properties:
                            error:
                              type: string
                            sku:
                              type: string
                          type: object
                        type: array
                      pushed:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trigger a Magento push.
      tags:
      - Product Information (PIM)
  /pim/families:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - code: footwear
                  id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
                  labels:
                    en_US: Footwear
              schema:
                properties:
                  data:
                    items:
                      properties:
                        code:
                          type: string
                        id:
                          type: string
                        labels:
                          properties:
                            en_US:
                              type: string
                          type: object
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List product families for the tenant.
      tags:
      - Product Information (PIM)
  /pim/feeds:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - channel_code: google
                  format: xml
                  id: 5e6f7a8b-9c0d-4e1f-2a3b-4c5d6e7f8091
                  last_run_at: '2026-07-15T06:00:00+00:00'
                  last_run_status: success
                  name: Google Shopping
              schema:
                properties:
                  data:
                    items:
                      properties:
                        channel_code:
                          type: string
                        format:
                          type: string
                        id:
                          type: string
                        last_run_at:
                          type: string
                        last_run_status:
                          type: string
                        name:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List feed templates for the tenant.
      tags:
      - Product Information (PIM)
  /pim/feeds/{feed_uuid}/generate:
    post:
      parameters:
      - in: path
        name: feed_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  file_key: pim/feeds/5e6f7a8b/google-2026-07-17.xml
                  generated: true
                  product_count: 120
              schema:
                properties:
                  data:
                    properties:
                      file_key:
                        type: string
                      generated:
                        type: boolean
                      product_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Trigger immediate generation of a feed and save it to storage.
      tags:
      - Product Information (PIM)
  /pim/import:
    post:
      description: "Multipart form fields:\n  file       — the import file\n  format\
        \     — csv | xlsx | json | xml  (optional; auto-detected from filename)\n\
        \  field_map  — JSON string {source_col: pim_target}  (optional)"
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  imported: 118
                  job_uuid: 7b3e1c2a-9f0d-4a11-8e2b-1c3d4e5f6a7b
                  skipped: 2
                  status: completed
                  total_rows: 120
              schema:
                properties:
                  data:
                    properties:
                      imported:
                        type: integer
                      job_uuid:
                        type: string
                      skipped:
                        type: integer
                      status:
                        type: string
                      total_rows:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: POST /api/v1/pim/import
      tags:
      - Product Information (PIM)
  /pim/import/{job_uuid}:
    get:
      parameters:
      - in: path
        name: job_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T14:03:00+00:00'
                  error_count: 2
                  errors:
                  - error: Missing SKU
                    row: 44
                  finished_at: '2026-07-17T14:03:12+00:00'
                  format: csv
                  imported: 118
                  skipped: 2
                  status: completed
                  total_rows: 120
                  uuid: 7b3e1c2a-9f0d-4a11-8e2b-1c3d4e5f6a7b
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      error_count:
                        type: integer
                      errors:
                        items:
                          properties:
                            error:
                              type: string
                            row:
                              type: integer
                          type: object
                        type: array
                      finished_at:
                        type: string
                      format:
                        type: string
                      imported:
                        type: integer
                      skipped:
                        type: integer
                      status:
                        type: string
                      total_rows:
                        type: integer
                      uuid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Return job status + summary.
      tags:
      - Product Information (PIM)
  /pim/products:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T12:00:00+00:00'
                  enabled: true
                  family_id: null
                  id: 7c6b5a4d-3e2f-4a1b-9c8d-0e1f2a3b4c5d
                  sku: SKU-001
                  status: draft
                  updated_at: '2026-07-10T09:30:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        enabled:
                          type: boolean
                        family_id:
                          nullable: true
                        id:
                          type: string
                        sku:
                          type: string
                        status:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List products for the authenticated tenant.
      tags:
      - Product Information (PIM)
    post:
      requestBody:
        content:
          application/json:
            example:
              enabled: true
              family_id: null
              sku: SKU-001
              status: draft
            schema:
              properties:
                enabled:
                  type: boolean
                family_id:
                  nullable: true
                sku:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T12:00:00+00:00'
                  enabled: true
                  family_id: null
                  id: 7c6b5a4d-3e2f-4a1b-9c8d-0e1f2a3b4c5d
                  sku: SKU-001
                  status: draft
                  updated_at: '2026-07-10T09:30:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      enabled:
                        type: boolean
                      family_id:
                        nullable: true
                      id:
                        type: string
                      sku:
                        type: string
                      status:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new product.
      tags:
      - Product Information (PIM)
  /pim/products/{prod_uuid}:
    delete:
      parameters:
      - in: path
        name: prod_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Archive a product (soft-delete).
      tags:
      - Product Information (PIM)
    get:
      parameters:
      - in: path
        name: prod_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T12:00:00+00:00'
                  enabled: true
                  family_id: null
                  id: 7c6b5a4d-3e2f-4a1b-9c8d-0e1f2a3b4c5d
                  sku: SKU-001
                  status: draft
                  updated_at: '2026-07-10T09:30:00+00:00'
                  variants:
                  - barcode: 0123456789012
                    id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                    is_active: true
                    position: 0
                    prices:
                    - amount: '19.99'
                      compare_at: '24.99'
                      currency: USD
                    sku: SKU-001-RED
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      enabled:
                        type: boolean
                      family_id:
                        nullable: true
                      id:
                        type: string
                      sku:
                        type: string
                      status:
                        type: string
                      updated_at:
                        type: string
                      variants:
                        items:
                          properties:
                            barcode:
                              type: string
                            id:
                              type: string
                            is_active:
                              type: boolean
                            position:
                              type: integer
                            prices:
                              items:
                                properties:
                                  amount:
                                    type: string
                                  compare_at:
                                    type: string
                                  currency:
                                    type: string
                                type: object
                              type: array
                            sku:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single product with its variants.
      tags:
      - Product Information (PIM)
    put:
      parameters:
      - in: path
        name: prod_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              enabled: true
              sku: SKU-001
              status: active
            schema:
              properties:
                enabled:
                  type: boolean
                sku:
                  type: string
                status:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T12:00:00+00:00'
                  enabled: true
                  family_id: null
                  id: 7c6b5a4d-3e2f-4a1b-9c8d-0e1f2a3b4c5d
                  sku: SKU-001
                  status: draft
                  updated_at: '2026-07-10T09:30:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      enabled:
                        type: boolean
                      family_id:
                        nullable: true
                      id:
                        type: string
                      sku:
                        type: string
                      status:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a product's top-level fields.
      tags:
      - Product Information (PIM)
  /pim/products/{prod_uuid}/variants:
    get:
      parameters:
      - in: path
        name: prod_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - barcode: 0123456789012
                  id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  is_active: true
                  position: 0
                  prices:
                  - amount: '19.99'
                    compare_at: '24.99'
                    currency: USD
                  sku: SKU-001-RED
              schema:
                properties:
                  data:
                    items:
                      properties:
                        barcode:
                          type: string
                        id:
                          type: string
                        is_active:
                          type: boolean
                        position:
                          type: integer
                        prices:
                          items:
                            properties:
                              amount:
                                type: string
                              compare_at:
                                type: string
                              currency:
                                type: string
                            type: object
                          type: array
                        sku:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List variants for a product.
      tags:
      - Product Information (PIM)
    post:
      parameters:
      - in: path
        name: prod_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              barcode: 0123456789012
              is_active: true
              position: 0
              sku: SKU-001-RED
            schema:
              properties:
                barcode:
                  type: string
                is_active:
                  type: boolean
                position:
                  type: integer
                sku:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  barcode: 0123456789012
                  id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  is_active: true
                  position: 0
                  prices:
                  - amount: '19.99'
                    compare_at: '24.99'
                    currency: USD
                  sku: SKU-001-RED
              schema:
                properties:
                  data:
                    properties:
                      barcode:
                        type: string
                      id:
                        type: string
                      is_active:
                        type: boolean
                      position:
                        type: integer
                      prices:
                        items:
                          properties:
                            amount:
                              type: string
                            compare_at:
                              type: string
                            currency:
                              type: string
                          type: object
                        type: array
                      sku:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a variant for a product.
      tags:
      - Product Information (PIM)
  /platformmessaging/flows:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - completed: 210
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: Onboarding Tour
                  published_at: '2026-07-01T12:00:00+00:00'
                  shown: 320
                  status: published
                  type: tour
                  updated_at: '2026-07-10T14:30:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        completed:
                          type: integer
                        id:
                          type: string
                        name:
                          type: string
                        published_at:
                          type: string
                        shown:
                          type: integer
                        status:
                          type: string
                        type:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get platformmessaging flows
      tags:
      - Platform Messaging
  /platformmessaging/flows/{uuid}/analytics:
    get:
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed: 210
                  completion_rate: 65.6
                  dismissed: 40
                  funnel:
                  - title: Welcome
                    views: 320
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: Onboarding Tour
                  shown: 320
                  status: published
              schema:
                properties:
                  data:
                    properties:
                      completed:
                        type: integer
                      completion_rate:
                        type: number
                      dismissed:
                        type: integer
                      funnel:
                        items:
                          properties:
                            title:
                              type: string
                            views:
                              type: integer
                          type: object
                        type: array
                      id:
                        type: string
                      name:
                        type: string
                      shown:
                        type: integer
                      status:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get platformmessaging flows uuid analytics
      tags:
      - Platform Messaging
  /pr/boards:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  boards:
                  - auth_mode: public
                    board_mode: public
                    created_at: '2026-06-01T09:00:00+00:00'
                    is_published: true
                    name: Feature Requests
                    request_count: 24
                    slug: feature-requests
                    tagline: Tell us what to build next.
                    uid: b1a2c3d4-e5f6-7890-abcd-ef0123456789
                  count: 1
              schema:
                properties:
                  data:
                    properties:
                      boards:
                        items:
                          properties:
                            auth_mode:
                              type: string
                            board_mode:
                              type: string
                            created_at:
                              type: string
                            is_published:
                              type: boolean
                            name:
                              type: string
                            request_count:
                              type: integer
                            slug:
                              type: string
                            tagline:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all Product Request boards for the tenant.
      tags:
      - Product Requests
  /pr/boards/{board_uid}:
    get:
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  auth_mode: public
                  board_mode: public
                  created_at: '2026-06-01T09:00:00+00:00'
                  is_published: true
                  name: Feature Requests
                  request_count: 24
                  slug: feature-requests
                  tagline: Tell us what to build next.
                  uid: b1a2c3d4-e5f6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      auth_mode:
                        type: string
                      board_mode:
                        type: string
                      created_at:
                        type: string
                      is_published:
                        type: boolean
                      name:
                        type: string
                      request_count:
                        type: integer
                      slug:
                        type: string
                      tagline:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single board by UUID.
      tags:
      - Product Requests
  /pr/boards/{board_uid}/requests:
    get:
      description: Paginated list of requests on a board. Filter with `?status=`,
        `?severity=`, `?q=`, and page with `?limit=` / `?offset=`.
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PrRequest'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List feature requests
      tags:
      - Product Requests
    post:
      description: Create a request. Pass board custom fields via the `custom_fields`
        object (lists are allowed for multi-select). Attachment fields are upload-only
        and cannot be set here.
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrRequestInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PrRequest'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Submit a feature request
      tags:
      - Product Requests
  /pr/boards/{board_uid}/requests/{req_uid}:
    get:
      description: Returns the full request including `custom_fields` and `attachments`.
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      - in: path
        name: req_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PrRequest'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a feature request
      tags:
      - Product Requests
    patch:
      description: 'Update admin fields: status, priority, product_response, product_eta,
        internal_notes, is_public, tags.'
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      - in: path
        name: req_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PrRequest'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a feature request
      tags:
      - Product Requests
  /pr/boards/{board_uid}/requests/{req_uid}/comments:
    get:
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      - in: path
        name: req_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  comments:
                  - author_email: ada@example.com
                    author_name: Ada Lovelace
                    body: Great idea, upvoted!
                    created_at: '2026-07-02T09:00:00+00:00'
                    is_staff: false
                    uid: c1a2c3d4-e5f6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      comments:
                        items:
                          properties:
                            author_email:
                              type: string
                            author_name:
                              type: string
                            body:
                              type: string
                            created_at:
                              type: string
                            is_staff:
                              type: boolean
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List comments on a feature request.
      tags:
      - Product Requests
    post:
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      - in: path
        name: req_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              author_email: ada@example.com
              author_name: Ada Lovelace
              body: Great idea, upvoted!
              is_staff: false
            schema:
              properties:
                author_email:
                  type: string
                author_name:
                  type: string
                body:
                  type: string
                is_staff:
                  type: boolean
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  author_email: ada@example.com
                  author_name: Ada Lovelace
                  body: Great idea, upvoted!
                  created_at: '2026-07-02T09:00:00+00:00'
                  is_staff: false
                  uid: c1a2c3d4-e5f6-7890-abcd-ef0123456789
              schema:
                properties:
                  data:
                    properties:
                      author_email:
                        type: string
                      author_name:
                        type: string
                      body:
                        type: string
                      created_at:
                        type: string
                      is_staff:
                        type: boolean
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Post a comment on a feature request.
      tags:
      - Product Requests
  /pr/boards/{board_uid}/requests/{req_uid}/vote:
    post:
      description: 'Body: { "value": 1 }   (1=upvote, -1=downvote, 0=retract)'
      parameters:
      - in: path
        name: board_uid
        required: true
        schema:
          type: string
      - in: path
        name: req_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              value: 1
            schema:
              properties:
                value:
                  type: integer
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  downvote_count: 1
                  upvote_count: 43
              schema:
                properties:
                  data:
                    properties:
                      downvote_count:
                        type: integer
                      upvote_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Cast or retract a vote.
      tags:
      - Product Requests
  /project-tasks/{task_id}:
    delete:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: t_7a6b5c4d3e2f
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a task.
      tags:
      - Project Tasks
    get:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee_id: 42
                  assignee_name: Alice Martin
                  column_id: c_1a2b3c4d5e6f
                  comments:
                  - author_name: Alice Martin
                    body: Looks good to me.
                    created_at: '2026-07-03T08:15:00+00:00'
                    id: cm_5e4d3c2b1a09
                    task_id: t_7a6b5c4d3e2f
                    updated_at: '2026-07-03T08:15:00+00:00'
                    user_id: 42
                  created_at: '2026-07-02T10:45:00+00:00'
                  description: Write hero + features sections
                  due_date: '2026-07-20'
                  id: t_7a6b5c4d3e2f
                  is_overdue: false
                  labels:
                  - color: '#ef4444'
                    id: lb_11aa22bb33cc
                    project_id: p_9f8e7d6c5b4a
                    title: bug
                  order: 1
                  priority: medium
                  project_id: p_9f8e7d6c5b4a
                  subtask_count: 3
                  subtask_done_count: 1
                  subtasks:
                  - created_at: '2026-07-02T11:00:00+00:00'
                    id: s_3c2b1a09f8e7
                    is_done: false
                    order: 0
                    task_id: t_7a6b5c4d3e2f
                    title: Collect brand assets
                  title: Draft homepage copy
                  updated_at: '2026-07-15T13:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee_id:
                        type: integer
                      assignee_name:
                        type: string
                      column_id:
                        type: string
                      comments:
                        items:
                          properties:
                            author_name:
                              type: string
                            body:
                              type: string
                            created_at:
                              type: string
                            id:
                              type: string
                            task_id:
                              type: string
                            updated_at:
                              type: string
                            user_id:
                              type: integer
                          type: object
                        type: array
                      created_at:
                        type: string
                      description:
                        type: string
                      due_date:
                        type: string
                      id:
                        type: string
                      is_overdue:
                        type: boolean
                      labels:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: string
                            project_id:
                              type: string
                            title:
                              type: string
                          type: object
                        type: array
                      order:
                        type: integer
                      priority:
                        type: string
                      project_id:
                        type: string
                      subtask_count:
                        type: integer
                      subtask_done_count:
                        type: integer
                      subtasks:
                        items:
                          properties:
                            created_at:
                              type: string
                            id:
                              type: string
                            is_done:
                              type: boolean
                            order:
                              type: integer
                            task_id:
                              type: string
                            title:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single task with subtasks and comments.
      tags:
      - Project Tasks
    patch:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              column_id: c_1a2b3c4d5e6f
              due_date: '2026-07-20'
              label_ids:
              - lb_11aa22bb33cc
              priority: high
              title: Draft homepage copy
            schema:
              properties:
                column_id:
                  type: string
                due_date:
                  type: string
                label_ids:
                  items:
                    type: string
                  type: array
                priority:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee_id: 42
                  assignee_name: Alice Martin
                  column_id: c_1a2b3c4d5e6f
                  created_at: '2026-07-02T10:45:00+00:00'
                  description: Write hero + features sections
                  due_date: '2026-07-20'
                  id: t_7a6b5c4d3e2f
                  is_overdue: false
                  labels:
                  - color: '#ef4444'
                    id: lb_11aa22bb33cc
                    project_id: p_9f8e7d6c5b4a
                    title: bug
                  order: 1
                  priority: medium
                  project_id: p_9f8e7d6c5b4a
                  subtask_count: 3
                  subtask_done_count: 1
                  subtasks:
                  - created_at: '2026-07-02T11:00:00+00:00'
                    id: s_3c2b1a09f8e7
                    is_done: false
                    order: 0
                    task_id: t_7a6b5c4d3e2f
                    title: Collect brand assets
                  title: Draft homepage copy
                  updated_at: '2026-07-15T13:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee_id:
                        type: integer
                      assignee_name:
                        type: string
                      column_id:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      due_date:
                        type: string
                      id:
                        type: string
                      is_overdue:
                        type: boolean
                      labels:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: string
                            project_id:
                              type: string
                            title:
                              type: string
                          type: object
                        type: array
                      order:
                        type: integer
                      priority:
                        type: string
                      project_id:
                        type: string
                      subtask_count:
                        type: integer
                      subtask_done_count:
                        type: integer
                      subtasks:
                        items:
                          properties:
                            created_at:
                              type: string
                            id:
                              type: string
                            is_done:
                              type: boolean
                            order:
                              type: integer
                            task_id:
                              type: string
                            title:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a task.
      tags:
      - Project Tasks
  /project-tasks/{task_id}/attachments:
    get:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-14T10:00:00+00:00'
                  file_size: 204800
                  id: aa11bb22-0000-1111-2222-333344445555
                  mime_type: application/pdf
                  original_filename: design-spec.pdf
                  uploaded_by: Jane Doe
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        file_size:
                          type: integer
                        id:
                          type: string
                        mime_type:
                          type: string
                        original_filename:
                          type: string
                        uploaded_by:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List attachments for a task.
      tags:
      - Project Tasks
    post:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-14T10:00:00+00:00'
                  file_size: 204800
                  id: aa11bb22-0000-1111-2222-333344445555
                  mime_type: application/pdf
                  original_filename: design-spec.pdf
                  uploaded_by: Jane Doe
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      file_size:
                        type: integer
                      id:
                        type: string
                      mime_type:
                        type: string
                      original_filename:
                        type: string
                      uploaded_by:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Upload a file attachment to a task (multipart, field name 'file').
      tags:
      - Project Tasks
  /project-tasks/{task_id}/attachments/{attachment_id}:
    delete:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: path
        name: attachment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: aa11bb22-0000-1111-2222-333344445555
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a task attachment.
      tags:
      - Project Tasks
  /project-tasks/{task_id}/comments:
    get:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - author_name: Alice Martin
                  body: Looks good to me.
                  created_at: '2026-07-03T08:15:00+00:00'
                  id: cm_5e4d3c2b1a09
                  task_id: t_7a6b5c4d3e2f
                  updated_at: '2026-07-03T08:15:00+00:00'
                  user_id: 42
              schema:
                properties:
                  data:
                    items:
                      properties:
                        author_name:
                          type: string
                        body:
                          type: string
                        created_at:
                          type: string
                        id:
                          type: string
                        task_id:
                          type: string
                        updated_at:
                          type: string
                        user_id:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List comments on a task.
      tags:
      - Project Tasks
    post:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Looks good to me.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  author_name: Alice Martin
                  body: Looks good to me.
                  created_at: '2026-07-03T08:15:00+00:00'
                  id: cm_5e4d3c2b1a09
                  task_id: t_7a6b5c4d3e2f
                  updated_at: '2026-07-03T08:15:00+00:00'
                  user_id: 42
              schema:
                properties:
                  data:
                    properties:
                      author_name:
                        type: string
                      body:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: string
                      task_id:
                        type: string
                      updated_at:
                        type: string
                      user_id:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Post a comment on a task.
      tags:
      - Project Tasks
  /project-tasks/{task_id}/comments/{comment_id}:
    delete:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: path
        name: comment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: cm_5e4d3c2b1a09
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a comment (own comments only).
      tags:
      - Project Tasks
    patch:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: path
        name: comment_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Edited comment.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  author_name: Alice Martin
                  body: Looks good to me.
                  created_at: '2026-07-03T08:15:00+00:00'
                  id: cm_5e4d3c2b1a09
                  task_id: t_7a6b5c4d3e2f
                  updated_at: '2026-07-03T08:15:00+00:00'
                  user_id: 42
              schema:
                properties:
                  data:
                    properties:
                      author_name:
                        type: string
                      body:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: string
                      task_id:
                        type: string
                      updated_at:
                        type: string
                      user_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Edit a comment (own comments only).
      tags:
      - Project Tasks
  /project-tasks/{task_id}/subtasks:
    get:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-02T11:00:00+00:00'
                  id: s_3c2b1a09f8e7
                  is_done: false
                  order: 0
                  task_id: t_7a6b5c4d3e2f
                  title: Collect brand assets
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        id:
                          type: string
                        is_done:
                          type: boolean
                        order:
                          type: integer
                        task_id:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List subtasks for a task.
      tags:
      - Project Tasks
    post:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              title: Collect brand assets
            schema:
              properties:
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-02T11:00:00+00:00'
                  id: s_3c2b1a09f8e7
                  is_done: false
                  order: 0
                  task_id: t_7a6b5c4d3e2f
                  title: Collect brand assets
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      id:
                        type: string
                      is_done:
                        type: boolean
                      order:
                        type: integer
                      task_id:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add a subtask.
      tags:
      - Project Tasks
  /project-tasks/{task_id}/subtasks/{subtask_id}:
    delete:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: path
        name: subtask_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: s_3c2b1a09f8e7
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a subtask.
      tags:
      - Project Tasks
    patch:
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          type: string
      - in: path
        name: subtask_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              is_done: true
              order: 1
              title: Collect brand assets
            schema:
              properties:
                is_done:
                  type: boolean
                order:
                  type: integer
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-02T11:00:00+00:00'
                  id: s_3c2b1a09f8e7
                  is_done: false
                  order: 0
                  task_id: t_7a6b5c4d3e2f
                  title: Collect brand assets
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      id:
                        type: string
                      is_done:
                        type: boolean
                      order:
                        type: integer
                      task_id:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a subtask (title or is_done).
      tags:
      - Project Tasks
  /projects:
    get:
      description: Returns paginated list of projects. Filter archived with `?archived=true|false`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: archived
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Project'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List projects
      tags:
      - Project Manager
    post:
      description: Create a new project. Three default columns (To Do, In Progress,
        Done) are created automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Project'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create project
      tags:
      - Project Manager
  /projects/{project_id}:
    delete:
      description: Permanently delete a project and all its tasks, columns, and labels.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete project
      tags:
      - Project Manager
    get:
      description: Returns a project with its columns.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Project'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get project
      tags:
      - Project Manager
    patch:
      description: Update title, description, color, icon, or archive status.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Project'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update project
      tags:
      - Project Manager
  /projects/{project_id}/columns:
    get:
      description: List all columns for a project. Pass `?include_tasks=true` to embed
        tasks in each column.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: query
        name: include_tasks
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ProjectColumn'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List columns
      tags:
      - Project Manager
    post:
      description: Add a new column to a project.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectColumnInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectColumn'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create column
      tags:
      - Project Manager
  /projects/{project_id}/columns/{column_id}:
    delete:
      description: Delete a column. Tasks in this column are moved to an unassigned
        state.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: column_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete column
      tags:
      - Project Manager
    patch:
      description: Update column title, color, order, or done status.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: column_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectColumnInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectColumn'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update column
      tags:
      - Project Manager
  /projects/{project_id}/custom-fields:
    get:
      description: Returns all custom field definitions for a project.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ProjectCustomField'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List project custom fields
      tags:
      - Project Manager
    post:
      description: 'Create a new custom field for a project.


        **field_type** options: `short_text` (max 256 chars), `long_text` (max 5000
        chars), `dropdown` (provide `options` array), `yes_no`.'
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCustomFieldInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectCustomField'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create project custom field
      tags:
      - Project Manager
  /projects/{project_id}/custom-fields/{field_id}:
    delete:
      description: Delete a custom field and remove all stored values from tasks.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: field_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete project custom field
      tags:
      - Project Manager
    patch:
      description: Update title, tooltip, options, is_required, or is_enabled.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: field_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCustomFieldInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectCustomField'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update project custom field
      tags:
      - Project Manager
  /projects/{project_id}/labels:
    get:
      description: Returns all labels defined for a project.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/TaskLabel'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List labels
      tags:
      - Project Manager
    post:
      description: Define a new label for a project.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskLabelInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/TaskLabel'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create label
      tags:
      - Project Manager
  /projects/{project_id}/labels/{label_id}:
    delete:
      description: Delete a label and remove it from all tasks.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: label_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete label
      tags:
      - Project Manager
    patch:
      description: Rename a label or change its color.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: path
        name: label_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskLabelInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/TaskLabel'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update label
      tags:
      - Project Manager
  /projects/{project_id}/members:
    get:
      description: 'Returns an array of member objects with ``id``, ``user_id``, ``name``,

        ``email``, ``role`` (owner | manager | member | readonly), and

        ``joined_at``.'
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - email: alice@example.com
                  id: m_6f5e4d3c2b1a
                  joined_at: '2026-07-01T09:30:00+00:00'
                  name: Alice Martin
                  role: member
                  user_id: 42
              schema:
                properties:
                  data:
                    items:
                      properties:
                        email:
                          type: string
                        id:
                          type: string
                        joined_at:
                          type: string
                        name:
                          type: string
                        role:
                          type: string
                        user_id:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all members of a project.
      tags:
      - Project Manager
  /projects/{project_id}/members/invite:
    post:
      description: "**Request body** (JSON):\n\n.. code-block:: json\n\n    {\n  \
        \    \"emails\": [\"alice@example.com\", \"bob@example.com\"],\n      \"role\"\
        : \"member\"\n    }\n\n``role`` must be one of ``manager``, ``member``, or\
        \ ``readonly``\n(default: ``member``).\n\nReturns ``{ \"sent\": N, \"skipped\"\
        : N }`` where *skipped* counts\naddresses that are already members or have\
        \ a pending invite."
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              emails:
              - alice@example.com
              - bob@example.com
              role: member
            schema:
              properties:
                emails:
                  items:
                    type: string
                  type: array
                role:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  sent: 2
                  skipped: 0
              schema:
                properties:
                  data:
                    properties:
                      sent:
                        type: integer
                      skipped:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Invite one or more people to join a project.
      tags:
      - Project Manager
  /projects/{project_id}/members/{member_id}:
    delete:
      description: 'The project owner cannot be removed. Returns ``{ "deleted": true
        }``.'
      parameters:
      - in: path
        name: member_id
        required: true
        schema:
          type: string
      - in: path
        name: project_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: m_6f5e4d3c2b1a
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Remove a member from a project.
      tags:
      - Project Manager
  /projects/{project_id}/members/{member_id}/role:
    patch:
      description: "**Request body** (JSON):\n\n.. code-block:: json\n\n    { \"role\"\
        : \"manager\" }\n\n``role`` must be ``manager``, ``member``, or ``readonly``.\n\
        The owner's role cannot be changed."
      parameters:
      - in: path
        name: member_id
        required: true
        schema:
          type: string
      - in: path
        name: project_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              role: manager
            schema:
              properties:
                role:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  email: alice@example.com
                  id: m_6f5e4d3c2b1a
                  joined_at: '2026-07-01T09:30:00+00:00'
                  name: Alice Martin
                  role: member
                  user_id: 42
              schema:
                properties:
                  data:
                    properties:
                      email:
                        type: string
                      id:
                        type: string
                      joined_at:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      user_id:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Change a member's role.
      tags:
      - Project Manager
  /projects/{project_id}/tasks:
    get:
      description: Returns paginated tasks for a project. Filter by `?column_id=`,
        `?priority=low|medium|high|critical`, or `?assignee_id=`.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: column_id
        schema:
          type: integer
      - in: query
        name: priority
        schema:
          enum:
          - low
          - medium
          - high
          - critical
          type: string
      - in: query
        name: assignee_id
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Task'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List tasks
      tags:
      - Project Manager
    post:
      description: Create a new task in a project.
      parameters:
      - in: path
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Task'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create task
      tags:
      - Project Manager
  /prompts/libraries:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T09:00:00+00:00'
                  description: Prompts used by the support team.
                  git_branch: main
                  git_folder: prompts/
                  git_repo: acme/prompts
                  is_active: true
                  last_synced_at: '2026-07-17T14:00:00+00:00'
                  name: Support Prompts
                  slug: support-prompts
                  source_of_truth: totalctrl
                  sync_error: null
                  sync_status: synced
                  uid: lib_1a2b3c
                  updated_at: '2026-07-17T14:00:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        description:
                          type: string
                        git_branch:
                          type: string
                        git_folder:
                          type: string
                        git_repo:
                          type: string
                        is_active:
                          type: boolean
                        last_synced_at:
                          type: string
                        name:
                          type: string
                        slug:
                          type: string
                        source_of_truth:
                          type: string
                        sync_error:
                          nullable: true
                        sync_status:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all prompt libraries.
      tags:
      - AI Prompts
  /prompts/libraries/{lib_slug}:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:00:00+00:00'
                  description: Prompts used by the support team.
                  git_branch: main
                  git_folder: prompts/
                  git_repo: acme/prompts
                  is_active: true
                  last_synced_at: '2026-07-17T14:00:00+00:00'
                  name: Support Prompts
                  slug: support-prompts
                  source_of_truth: totalctrl
                  sync_error: null
                  sync_status: synced
                  uid: lib_1a2b3c
                  updated_at: '2026-07-17T14:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      git_branch:
                        type: string
                      git_folder:
                        type: string
                      git_repo:
                        type: string
                      is_active:
                        type: boolean
                      last_synced_at:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      source_of_truth:
                        type: string
                      sync_error:
                        nullable: true
                      sync_status:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single library.
      tags:
      - AI Prompts
  /prompts/{lib_slug}:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T09:00:00+00:00'
                  current_version_uid: ver_9z8y7x
                  description: Summarize a support ticket thread.
                  git_path: prompts/ticket-summary.md
                  is_archived: false
                  library_uid: lib_1a2b3c
                  name: Ticket Summary
                  prompt_type: chat
                  slug: ticket-summary
                  uid: prm_1a2b3c
                  updated_at: '2026-07-17T14:00:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        current_version_uid:
                          type: string
                        description:
                          type: string
                        git_path:
                          type: string
                        is_archived:
                          type: boolean
                        library_uid:
                          type: string
                        name:
                          type: string
                        prompt_type:
                          type: string
                        slug:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List prompts in library.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/datasets:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-01T09:00:00+00:00'
                  description: Golden examples for summary quality.
                  is_archived: false
                  library_uid: lib_1a2b3c
                  name: Ticket Summary Eval Set
                  row_count: 25
                  uid: ds_1a2b3c
                  updated_at: '2026-07-17T14:00:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        description:
                          type: string
                        is_archived:
                          type: boolean
                        library_uid:
                          type: string
                        name:
                          type: string
                        row_count:
                          type: integer
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List evaluation datasets in library.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/datasets/{ds_uid}:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: ds_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-01T09:00:00+00:00'
                  description: Golden examples for summary quality.
                  is_archived: false
                  library_uid: lib_1a2b3c
                  name: Ticket Summary Eval Set
                  row_count: 25
                  rows:
                  - created_at: '2026-07-01T09:00:00+00:00'
                    dataset_uid: ds_1a2b3c
                    expected_output: Login failure reported.
                    input_variables:
                      ticket: Customer cannot log in.
                    sort_order: 0
                    tags:
                    - login
                    uid: dsr_1a2b3c
                  uid: ds_1a2b3c
                  updated_at: '2026-07-17T14:00:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      is_archived:
                        type: boolean
                      library_uid:
                        type: string
                      name:
                        type: string
                      row_count:
                        type: integer
                      rows:
                        items:
                          properties:
                            created_at:
                              type: string
                            dataset_uid:
                              type: string
                            expected_output:
                              type: string
                            input_variables:
                              properties:
                                ticket:
                                  type: string
                              type: object
                            sort_order:
                              type: integer
                            tags:
                              items:
                                type: string
                              type: array
                            uid:
                              type: string
                          type: object
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get dataset with rows.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  body: 'Summarize the following ticket: {{ticket}}'
                  compiled_body: 'Summarize the following ticket: Customer cannot
                    log in.'
                  label: production
                  library_slug: support-prompts
                  model: claude-3-5-sonnet
                  model_params:
                    temperature: 0.2
                  prompt_slug: ticket-summary
                  prompt_type: chat
                  token_estimate: 128
                  variables:
                  - ticket
                  version_number: 3
                  version_uid: ver_9z8y7x
              schema:
                properties:
                  data:
                    properties:
                      body:
                        type: string
                      compiled_body:
                        type: string
                      label:
                        type: string
                      library_slug:
                        type: string
                      model:
                        type: string
                      model_params:
                        properties:
                          temperature:
                            type: number
                        type: object
                      prompt_slug:
                        type: string
                      prompt_type:
                        type: string
                      token_estimate:
                        type: integer
                      variables:
                        items:
                          type: string
                        type: array
                      version_number:
                        type: integer
                      version_uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Fetch a prompt at a label (runtime endpoint).
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/evals:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - avg_score: 87.5
                  created_at: '2026-07-17T13:59:00+00:00'
                  dataset_name: Ticket Summary Eval Set
                  dataset_uid: ds_1a2b3c
                  error_message: null
                  finished_at: '2026-07-17T14:02:00+00:00'
                  judge_model: claude-3-5-sonnet
                  prompt_uid: prm_1a2b3c
                  row_count: 25
                  score_method: llm
                  scored_count: 25
                  started_at: '2026-07-17T14:00:00+00:00'
                  status: completed
                  uid: run_1a2b3c
                  version_number: 3
                  version_uid: ver_9z8y7x
              schema:
                properties:
                  data:
                    items:
                      properties:
                        avg_score:
                          type: number
                        created_at:
                          type: string
                        dataset_name:
                          type: string
                        dataset_uid:
                          type: string
                        error_message:
                          nullable: true
                        finished_at:
                          type: string
                        judge_model:
                          type: string
                        prompt_uid:
                          type: string
                        row_count:
                          type: integer
                        score_method:
                          type: string
                        scored_count:
                          type: integer
                        started_at:
                          type: string
                        status:
                          type: string
                        uid:
                          type: string
                        version_number:
                          type: integer
                        version_uid:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List eval runs for a prompt.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/evals/{run_uid}:
    get:
      parameters:
      - in: path
        name: run_uid
        required: true
        schema:
          type: string
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  avg_score: 87.5
                  created_at: '2026-07-17T13:59:00+00:00'
                  dataset_name: Ticket Summary Eval Set
                  dataset_uid: ds_1a2b3c
                  error_message: null
                  finished_at: '2026-07-17T14:02:00+00:00'
                  judge_model: claude-3-5-sonnet
                  prompt_uid: prm_1a2b3c
                  row_count: 25
                  score_method: llm
                  scored_count: 25
                  scores:
                  - actual_output: The customer reports being unable to log in.
                    created_at: '2026-07-17T14:01:00+00:00'
                    dataset_row_uid: dsr_1a2b3c
                    error_message: null
                    eval_run_uid: run_1a2b3c
                    score: 90
                    score_rationale: Accurate and concise.
                    scored_at: '2026-07-17T14:01:00+00:00'
                    scored_by: llm
                    uid: scr_1a2b3c
                  started_at: '2026-07-17T14:00:00+00:00'
                  status: completed
                  uid: run_1a2b3c
                  version_number: 3
                  version_uid: ver_9z8y7x
              schema:
                properties:
                  data:
                    properties:
                      avg_score:
                        type: number
                      created_at:
                        type: string
                      dataset_name:
                        type: string
                      dataset_uid:
                        type: string
                      error_message:
                        nullable: true
                      finished_at:
                        type: string
                      judge_model:
                        type: string
                      prompt_uid:
                        type: string
                      row_count:
                        type: integer
                      score_method:
                        type: string
                      scored_count:
                        type: integer
                      scores:
                        items:
                          properties:
                            actual_output:
                              type: string
                            created_at:
                              type: string
                            dataset_row_uid:
                              type: string
                            error_message:
                              nullable: true
                            eval_run_uid:
                              type: string
                            score:
                              type: number
                            score_rationale:
                              type: string
                            scored_at:
                              type: string
                            scored_by:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      started_at:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                      version_number:
                        type: integer
                      version_uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get eval run with scores.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/labels:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#22c55e'
                  is_system: true
                  name: production
                  updated_at: '2026-07-17T14:00:00+00:00'
                  version_number: 3
                  version_uid: ver_9z8y7x
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        is_system:
                          type: boolean
                        name:
                          type: string
                        updated_at:
                          type: string
                        version_number:
                          type: integer
                        version_uid:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all labels for a prompt.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/labels/{label_name}:
    put:
      parameters:
      - in: path
        name: label_name
        required: true
        schema:
          type: string
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              version_number: 3
            schema:
              properties:
                version_number:
                  type: integer
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  label_name: production
                  version_number: 3
              schema:
                properties:
                  data:
                    properties:
                      label_name:
                        type: string
                      version_number:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Move label to version.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/versions:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - body: 'Summarize the following ticket: {{ticket}}'
                  commit_message: Tighten summary instructions
                  created_at: '2026-07-17T14:00:00+00:00'
                  git_sha: a1b2c3d
                  is_pinned: false
                  model: claude-3-5-sonnet
                  model_params:
                    temperature: 0.2
                  prompt_uid: prm_1a2b3c
                  token_estimate: 128
                  uid: ver_9z8y7x
                  variables:
                  - ticket
                  version_number: 3
              schema:
                properties:
                  data:
                    items:
                      properties:
                        body:
                          type: string
                        commit_message:
                          type: string
                        created_at:
                          type: string
                        git_sha:
                          type: string
                        is_pinned:
                          type: boolean
                        model:
                          type: string
                        model_params:
                          properties:
                            temperature:
                              type: number
                          type: object
                        prompt_uid:
                          type: string
                        token_estimate:
                          type: integer
                        uid:
                          type: string
                        variables:
                          items:
                            type: string
                          type: array
                        version_number:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List versions, newest first.
      tags:
      - AI Prompts
    post:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: 'Summarize the following ticket: {{ticket}}'
              commit_message: Tighten summary instructions
              model: claude-3-5-sonnet
              model_params:
                temperature: 0.2
            schema:
              properties:
                body:
                  type: string
                commit_message:
                  type: string
                model:
                  type: string
                model_params:
                  properties:
                    temperature:
                      type: number
                  type: object
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T14:05:00+00:00'
                  uid: ver_new123
                  version_number: 4
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      uid:
                        type: string
                      version_number:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new version.
      tags:
      - AI Prompts
  /prompts/{lib_slug}/{slug}/versions/{version_number}:
    get:
      parameters:
      - in: path
        name: lib_slug
        required: true
        schema:
          type: string
      - in: path
        name: slug
        required: true
        schema:
          type: string
      - in: path
        name: version_number
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  body: 'Summarize the following ticket: {{ticket}}'
                  commit_message: Tighten summary instructions
                  created_at: '2026-07-17T14:00:00+00:00'
                  git_sha: a1b2c3d
                  is_pinned: false
                  model: claude-3-5-sonnet
                  model_params:
                    temperature: 0.2
                  prompt_uid: prm_1a2b3c
                  token_estimate: 128
                  uid: ver_9z8y7x
                  variables:
                  - ticket
                  version_number: 3
              schema:
                properties:
                  data:
                    properties:
                      body:
                        type: string
                      commit_message:
                        type: string
                      created_at:
                        type: string
                      git_sha:
                        type: string
                      is_pinned:
                        type: boolean
                      model:
                        type: string
                      model_params:
                        properties:
                          temperature:
                            type: number
                        type: object
                      prompt_uid:
                        type: string
                      token_estimate:
                        type: integer
                      uid:
                        type: string
                      variables:
                        items:
                          type: string
                        type: array
                      version_number:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single version.
      tags:
      - AI Prompts
  /session-replay/sessions:
    get:
      description: 'Query: ?has_errors=true ?has_rage_clicks=true ?min_struggle=N
        ?device=

        (desktop|mobile|tablet) ?user= (email/visitor substring) ?limit= (default

        25, max 100) ?offset=.'
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  sessions:
                  - ai_summary: Visitor hit a 500 on the payment step and rage-clicked
                      Submit.
                    chunk_count: 3
                    country_code: US
                    created_at: '2026-07-17T12:00:00+00:00'
                    device_type: desktop
                    duration_ms: 184200
                    ended_at: '2026-07-17T12:03:04+00:00'
                    error_count: 2
                    event_count: 1420
                    has_errors: true
                    has_rage_clicks: true
                    rage_click_count: 1
                    start_url: https://app.acme.com/checkout
                    started_at: '2026-07-17T12:00:00+00:00'
                    status: ended
                    struggle_score: 68
                    uid: sess_7b2c9e
                    user_email: jordan@acme.com
                    visitor_id: vis_18ac44
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      sessions:
                        items:
                          properties:
                            ai_summary:
                              type: string
                            chunk_count:
                              type: integer
                            country_code:
                              type: string
                            created_at:
                              type: string
                            device_type:
                              type: string
                            duration_ms:
                              type: integer
                            ended_at:
                              type: string
                            error_count:
                              type: integer
                            event_count:
                              type: integer
                            has_errors:
                              type: boolean
                            has_rage_clicks:
                              type: boolean
                            rage_click_count:
                              type: integer
                            start_url:
                              type: string
                            started_at:
                              type: string
                            status:
                              type: string
                            struggle_score:
                              type: integer
                            uid:
                              type: string
                            user_email:
                              type: string
                            visitor_id:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List recorded sessions (newest first).
      tags:
      - Session Replay
  /session-replay/sessions/{uid}:
    delete:
      description: (soft-delete). Idempotent.
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  uid: sess_7b2c9e
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      uid:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'GDPR delete: purge the session''s event blobs and null its PII'
      tags:
      - Session Replay
    get:
      description: themselves are fetched per chunk from the chunk endpoint.
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_summary: Visitor hit a 500 on the payment step and rage-clicked
                    Submit.
                  chunk_count: 3
                  chunks:
                  - https://api.totalctrl.app/api/v1/session-replay/sessions/sess_7b2c9e/chunks/0
                  - https://api.totalctrl.app/api/v1/session-replay/sessions/sess_7b2c9e/chunks/1
                  country_code: US
                  created_at: '2026-07-17T12:00:00+00:00'
                  device_type: desktop
                  duration_ms: 184200
                  ended_at: '2026-07-17T12:03:04+00:00'
                  error_count: 2
                  event_count: 1420
                  has_errors: true
                  has_rage_clicks: true
                  rage_click_count: 1
                  start_url: https://app.acme.com/checkout
                  started_at: '2026-07-17T12:00:00+00:00'
                  status: ended
                  struggle_score: 68
                  uid: sess_7b2c9e
                  user_email: jordan@acme.com
                  visitor_id: vis_18ac44
              schema:
                properties:
                  data:
                    properties:
                      ai_summary:
                        type: string
                      chunk_count:
                        type: integer
                      chunks:
                        items:
                          type: string
                        type: array
                      country_code:
                        type: string
                      created_at:
                        type: string
                      device_type:
                        type: string
                      duration_ms:
                        type: integer
                      ended_at:
                        type: string
                      error_count:
                        type: integer
                      event_count:
                        type: integer
                      has_errors:
                        type: boolean
                      has_rage_clicks:
                        type: boolean
                      rage_click_count:
                        type: integer
                      start_url:
                        type: string
                      started_at:
                        type: string
                      status:
                        type: string
                      struggle_score:
                        type: integer
                      uid:
                        type: string
                      user_email:
                        type: string
                      visitor_id:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Session metadata plus a manifest of event-chunk URLs. The rrweb events
      tags:
      - Session Replay
  /session-replay/sessions/{uid}/chunks/{index}:
    get:
      parameters:
      - in: path
        name: index
        required: true
        schema:
          type: string
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Raw event chunk bytes (msgpack+gzip rrweb events) for a session.
      tags:
      - Session Replay
  /signals:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  connectors:
                  - connector_type: stripe
                    events_received: 328
                    is_active: true
                    label: Stripe Webhooks
                    uid: c0nn3ct0r
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      connectors:
                        items:
                          properties:
                            connector_type:
                              type: string
                            events_received:
                              type: integer
                            is_active:
                              type: boolean
                            label:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List signal connectors.
      tags:
      - Signals
  /signals/{connector_uid}/events:
    get:
      parameters:
      - in: path
        name: connector_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  connector: Stripe Webhooks
                  events:
                  - created_at: '2026-07-17T14:00:00+00:00'
                    event_type: charge.succeeded
                    payload:
                      amount: 4200
                      currency: usd
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      connector:
                        type: string
                      events:
                        items:
                          properties:
                            created_at:
                              type: string
                            event_type:
                              type: string
                            payload:
                              properties:
                                amount:
                                  type: integer
                                currency:
                                  type: string
                              type: object
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Recent events for a connector.
      tags:
      - Signals
  /signing/envelopes:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - completed_at: '2026-07-14T10:05:00'
                  created_at: '2026-07-14T09:00:00'
                  expires_at: '2026-08-14T09:05:00'
                  id: e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5061
                  page_count: 8
                  recipients:
                  - decline_reason: null
                    declined_at: null
                    email: jane@example.com
                    id: r1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                    name: Jane Signer
                    order: 1
                    role: signer
                    signed_at: '2026-07-14T10:05:00'
                    status: signed
                    viewed_at: '2026-07-14T10:00:00'
                  sent_at: '2026-07-14T09:05:00'
                  sha256_hash: 9f2c8b1a4e7d6c5b0a3f2e1d8c7b6a594837261504f3e2d1c0b9a8f7e6d5c4b3
                  signed_count: 2
                  signer_count: 2
                  signing_order: true
                  status: completed
                  title: Master Services Agreement
              schema:
                properties:
                  data:
                    items:
                      properties:
                        completed_at:
                          type: string
                        created_at:
                          type: string
                        expires_at:
                          type: string
                        id:
                          type: string
                        page_count:
                          type: integer
                        recipients:
                          items:
                            properties:
                              decline_reason:
                                nullable: true
                              declined_at:
                                nullable: true
                              email:
                                type: string
                              id:
                                type: string
                              name:
                                type: string
                              order:
                                type: integer
                              role:
                                type: string
                              signed_at:
                                type: string
                              status:
                                type: string
                              viewed_at:
                                type: string
                            type: object
                          type: array
                        sent_at:
                          type: string
                        sha256_hash:
                          type: string
                        signed_count:
                          type: integer
                        signer_count:
                          type: integer
                        signing_order:
                          type: boolean
                        status:
                          type: string
                        title:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List Document Signing envelopes. Optional ?status= filter.
      tags:
      - Document Signing
  /signing/envelopes/{env_uuid}:
    get:
      parameters:
      - in: path
        name: env_uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed_at: '2026-07-14T10:05:00'
                  created_at: '2026-07-14T09:00:00'
                  expires_at: '2026-08-14T09:05:00'
                  id: e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5061
                  page_count: 8
                  recipients:
                  - decline_reason: null
                    declined_at: null
                    email: jane@example.com
                    id: r1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                    name: Jane Signer
                    order: 1
                    role: signer
                    signed_at: '2026-07-14T10:05:00'
                    status: signed
                    viewed_at: '2026-07-14T10:00:00'
                  sent_at: '2026-07-14T09:05:00'
                  sha256_hash: 9f2c8b1a4e7d6c5b0a3f2e1d8c7b6a594837261504f3e2d1c0b9a8f7e6d5c4b3
                  signed_count: 2
                  signer_count: 2
                  signing_order: true
                  status: completed
                  title: Master Services Agreement
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        type: string
                      created_at:
                        type: string
                      expires_at:
                        type: string
                      id:
                        type: string
                      page_count:
                        type: integer
                      recipients:
                        items:
                          properties:
                            decline_reason:
                              nullable: true
                            declined_at:
                              nullable: true
                            email:
                              type: string
                            id:
                              type: string
                            name:
                              type: string
                            order:
                              type: integer
                            role:
                              type: string
                            signed_at:
                              type: string
                            status:
                              type: string
                            viewed_at:
                              type: string
                          type: object
                        type: array
                      sent_at:
                        type: string
                      sha256_hash:
                        type: string
                      signed_count:
                        type: integer
                      signer_count:
                        type: integer
                      signing_order:
                        type: boolean
                      status:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get signing envelopes env_uuid
      tags:
      - Document Signing
  /signing/envelopes/{env_uuid}/events:
    get:
      parameters:
      - in: path
        name: env_uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - actor: jane@example.com
                  event_type: signed
                  ip_address: 203.0.113.24
                  meta:
                    field_count: 3
                  occurred_at: '2026-07-14T10:05:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        actor:
                          type: string
                        event_type:
                          type: string
                        ip_address:
                          type: string
                        meta:
                          properties:
                            field_count:
                              type: integer
                          type: object
                        occurred_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get signing envelopes env_uuid events
      tags:
      - Document Signing
  /signing/envelopes/{env_uuid}/send:
    post:
      parameters:
      - in: path
        name: env_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  completed_at: '2026-07-14T10:05:00'
                  created_at: '2026-07-14T09:00:00'
                  expires_at: '2026-08-14T09:05:00'
                  id: e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5061
                  page_count: 8
                  recipients:
                  - decline_reason: null
                    declined_at: null
                    email: jane@example.com
                    id: r1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                    name: Jane Signer
                    order: 1
                    role: signer
                    signed_at: '2026-07-14T10:05:00'
                    status: signed
                    viewed_at: '2026-07-14T10:00:00'
                  sent_at: '2026-07-14T09:05:00'
                  sha256_hash: 9f2c8b1a4e7d6c5b0a3f2e1d8c7b6a594837261504f3e2d1c0b9a8f7e6d5c4b3
                  signed_count: 2
                  signer_count: 2
                  signing_order: true
                  status: completed
                  title: Master Services Agreement
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        type: string
                      created_at:
                        type: string
                      expires_at:
                        type: string
                      id:
                        type: string
                      page_count:
                        type: integer
                      recipients:
                        items:
                          properties:
                            decline_reason:
                              nullable: true
                            declined_at:
                              nullable: true
                            email:
                              type: string
                            id:
                              type: string
                            name:
                              type: string
                            order:
                              type: integer
                            role:
                              type: string
                            signed_at:
                              type: string
                            status:
                              type: string
                            viewed_at:
                              type: string
                          type: object
                        type: array
                      sent_at:
                        type: string
                      sha256_hash:
                        type: string
                      signed_count:
                        type: integer
                      signer_count:
                        type: integer
                      signing_order:
                        type: boolean
                      status:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Send a draft envelope (must already have recipients + fields).
      tags:
      - Document Signing
  /signing/envelopes/{env_uuid}/void:
    post:
      parameters:
      - in: path
        name: env_uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              reason: Superseded by a new contract.
            schema:
              properties:
                reason:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  completed_at: '2026-07-14T10:05:00'
                  created_at: '2026-07-14T09:00:00'
                  expires_at: '2026-08-14T09:05:00'
                  id: e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5061
                  page_count: 8
                  recipients:
                  - decline_reason: null
                    declined_at: null
                    email: jane@example.com
                    id: r1a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6071
                    name: Jane Signer
                    order: 1
                    role: signer
                    signed_at: '2026-07-14T10:05:00'
                    status: signed
                    viewed_at: '2026-07-14T10:00:00'
                  sent_at: '2026-07-14T09:05:00'
                  sha256_hash: 9f2c8b1a4e7d6c5b0a3f2e1d8c7b6a594837261504f3e2d1c0b9a8f7e6d5c4b3
                  signed_count: 2
                  signer_count: 2
                  signing_order: true
                  status: completed
                  title: Master Services Agreement
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        type: string
                      created_at:
                        type: string
                      expires_at:
                        type: string
                      id:
                        type: string
                      page_count:
                        type: integer
                      recipients:
                        items:
                          properties:
                            decline_reason:
                              nullable: true
                            declined_at:
                              nullable: true
                            email:
                              type: string
                            id:
                              type: string
                            name:
                              type: string
                            order:
                              type: integer
                            role:
                              type: string
                            signed_at:
                              type: string
                            status:
                              type: string
                            viewed_at:
                              type: string
                          type: object
                        type: array
                      sent_at:
                        type: string
                      sha256_hash:
                        type: string
                      signed_count:
                        type: integer
                      signer_count:
                        type: integer
                      signing_order:
                        type: boolean
                      status:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create signing envelopes env_uuid void
      tags:
      - Document Signing
  /standards/context:
    get:
      description: "Query params (required: app_slug; optional: language, query):\n\
        \  app_slug  — ccms|wiki|creator|help_center|website\n  language  — BCP-47\
        \ code (default: en)\n  query     — topic hint (currently unused for filtering,\
        \ reserved)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  app_slug: wiki
                  glossary:
                  - abbreviation: null
                    approved_at: null
                    created_at: '2026-07-17T12:00:00'
                    definition: The step where a customer pays for their cart.
                    do_not_change: false
                    do_not_translate: false
                    entry_uid: b2c3d4e5-1111-2222-3333-444455556666
                    gender: null
                    language: en
                    part_of_speech: noun
                    plural_form: null
                    status: preferred
                    term: Checkout
                    translate_as: null
                    uid: c3d4e5f6-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    usage_note: null
                  language: en
                  style_rules:
                  - applies_to:
                    - wiki
                    - help_center
                    category: voice
                    created_at: '2026-07-17T12:00:00'
                    is_active: true
                    is_language_agnostic: true
                    locale:
                      created_at: '2026-07-17T12:00:00'
                      description: Prefer active voice over passive.
                      example_bad: An email is sent by the system.
                      example_good: The system sends an email.
                      is_disabled: false
                      language: en
                      locale_notes: null
                      rule_uid: d4e5f6a7-1111-2222-3333-444455556666
                      severity_override: null
                      uid: e5f6a7b8-1111-2222-3333-444455556666
                      updated_at: '2026-07-17T12:00:00'
                    locale_count: 1
                    name: Use active voice
                    notes: null
                    severity: preferred
                    uid: d4e5f6a7-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                  tone_profile:
                    applies_to:
                    - wiki
                    - help_center
                    created_at: '2026-07-17T12:00:00'
                    is_active: true
                    is_default: true
                    locale:
                      created_at: '2026-07-17T12:00:00'
                      donts:
                      - Avoid jargon
                      dos:
                      - Be concise
                      formality: professional
                      language: en
                      personality: Helpful and clear
                      pov: second_person
                      profile_uid: f6a7b8c9-1111-2222-3333-444455556666
                      sample_sentence: You can update your settings at any time.
                      uid: a7b8c9d0-1111-2222-3333-444455556666
                      updated_at: '2026-07-17T12:00:00'
                    name: Default brand voice
                    uid: f6a7b8c9-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      app_slug:
                        type: string
                      glossary:
                        items:
                          properties:
                            abbreviation:
                              nullable: true
                            approved_at:
                              nullable: true
                            created_at:
                              type: string
                            definition:
                              type: string
                            do_not_change:
                              type: boolean
                            do_not_translate:
                              type: boolean
                            entry_uid:
                              type: string
                            gender:
                              nullable: true
                            language:
                              type: string
                            part_of_speech:
                              type: string
                            plural_form:
                              nullable: true
                            status:
                              type: string
                            term:
                              type: string
                            translate_as:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                            usage_note:
                              nullable: true
                          type: object
                        type: array
                      language:
                        type: string
                      style_rules:
                        items:
                          properties:
                            applies_to:
                              items:
                                type: string
                              type: array
                            category:
                              type: string
                            created_at:
                              type: string
                            is_active:
                              type: boolean
                            is_language_agnostic:
                              type: boolean
                            locale:
                              properties:
                                created_at:
                                  type: string
                                description:
                                  type: string
                                example_bad:
                                  type: string
                                example_good:
                                  type: string
                                is_disabled:
                                  type: boolean
                                language:
                                  type: string
                                locale_notes:
                                  nullable: true
                                rule_uid:
                                  type: string
                                severity_override:
                                  nullable: true
                                uid:
                                  type: string
                                updated_at:
                                  type: string
                              type: object
                            locale_count:
                              type: integer
                            name:
                              type: string
                            notes:
                              nullable: true
                            severity:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      tone_profile:
                        properties:
                          applies_to:
                            items:
                              type: string
                            type: array
                          created_at:
                            type: string
                          is_active:
                            type: boolean
                          is_default:
                            type: boolean
                          locale:
                            properties:
                              created_at:
                                type: string
                              donts:
                                items:
                                  type: string
                                type: array
                              dos:
                                items:
                                  type: string
                                type: array
                              formality:
                                type: string
                              language:
                                type: string
                              personality:
                                type: string
                              pov:
                                type: string
                              profile_uid:
                                type: string
                              sample_sentence:
                                type: string
                              uid:
                                type: string
                              updated_at:
                                type: string
                            type: object
                          name:
                            type: string
                          uid:
                            type: string
                          updated_at:
                            type: string
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Combined brand/style context for AI writing.
      tags:
      - Standards & Compliance
  /standards/glossary:
    get:
      description: "Query params (all optional):\n  domain, status, language, search,\
        \ limit (default 50)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-07-17T12:00:00'
                  domain: product
                  image_key: null
                  is_active: true
                  slug: checkout
                  subject_area: null
                  term_count: 1
                  uid: b2c3d4e5-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        domain:
                          type: string
                        image_key:
                          nullable: true
                        is_active:
                          type: boolean
                        slug:
                          type: string
                        subject_area:
                          nullable: true
                        term_count:
                          type: integer
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List glossary entries.
      tags:
      - Standards & Compliance
    post:
      description: "Body JSON (required: term, language):\n  term, language, definition,\
        \ domain, status, do_not_translate"
      requestBody:
        content:
          application/json:
            example:
              definition: The step where a customer pays for their cart.
              do_not_translate: false
              domain: product
              language: en
              status: preferred
              term: Checkout
            schema:
              properties:
                definition:
                  type: string
                do_not_translate:
                  type: boolean
                domain:
                  type: string
                language:
                  type: string
                status:
                  type: string
                term:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00'
                  domain: product
                  image_key: null
                  is_active: true
                  slug: checkout
                  subject_area: null
                  term_count: 1
                  terms:
                  - abbreviation: null
                    approved_at: null
                    created_at: '2026-07-17T12:00:00'
                    definition: The step where a customer pays for their cart.
                    do_not_change: false
                    do_not_translate: false
                    entry_uid: b2c3d4e5-1111-2222-3333-444455556666
                    gender: null
                    language: en
                    part_of_speech: noun
                    plural_form: null
                    status: preferred
                    term: Checkout
                    translate_as: null
                    uid: c3d4e5f6-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    usage_note: null
                  uid: b2c3d4e5-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      domain:
                        type: string
                      image_key:
                        nullable: true
                      is_active:
                        type: boolean
                      slug:
                        type: string
                      subject_area:
                        nullable: true
                      term_count:
                        type: integer
                      terms:
                        items:
                          properties:
                            abbreviation:
                              nullable: true
                            approved_at:
                              nullable: true
                            created_at:
                              type: string
                            definition:
                              type: string
                            do_not_change:
                              type: boolean
                            do_not_translate:
                              type: boolean
                            entry_uid:
                              type: string
                            gender:
                              nullable: true
                            language:
                              type: string
                            part_of_speech:
                              type: string
                            plural_form:
                              nullable: true
                            status:
                              type: string
                            term:
                              type: string
                            translate_as:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                            usage_note:
                              nullable: true
                          type: object
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a glossary entry + initial term.
      tags:
      - Standards & Compliance
  /standards/glossary/{entry_uid}:
    delete:
      parameters:
      - in: path
        name: entry_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete entry and all its terms.
      tags:
      - Standards & Compliance
    get:
      parameters:
      - in: path
        name: entry_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00'
                  domain: product
                  image_key: null
                  is_active: true
                  slug: checkout
                  subject_area: null
                  term_count: 1
                  terms:
                  - abbreviation: null
                    approved_at: null
                    created_at: '2026-07-17T12:00:00'
                    definition: The step where a customer pays for their cart.
                    do_not_change: false
                    do_not_translate: false
                    entry_uid: b2c3d4e5-1111-2222-3333-444455556666
                    gender: null
                    language: en
                    part_of_speech: noun
                    plural_form: null
                    status: preferred
                    term: Checkout
                    translate_as: null
                    uid: c3d4e5f6-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    usage_note: null
                  uid: b2c3d4e5-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      domain:
                        type: string
                      image_key:
                        nullable: true
                      is_active:
                        type: boolean
                      slug:
                        type: string
                      subject_area:
                        nullable: true
                      term_count:
                        type: integer
                      terms:
                        items:
                          properties:
                            abbreviation:
                              nullable: true
                            approved_at:
                              nullable: true
                            created_at:
                              type: string
                            definition:
                              type: string
                            do_not_change:
                              type: boolean
                            do_not_translate:
                              type: boolean
                            entry_uid:
                              type: string
                            gender:
                              nullable: true
                            language:
                              type: string
                            part_of_speech:
                              type: string
                            plural_form:
                              nullable: true
                            status:
                              type: string
                            term:
                              type: string
                            translate_as:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                            usage_note:
                              nullable: true
                          type: object
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get entry with all terms.
      tags:
      - Standards & Compliance
    patch:
      description: "Body JSON (all optional):\n  domain, subject_area, is_active"
      parameters:
      - in: path
        name: entry_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              domain: product
              is_active: true
              subject_area: ecommerce
            schema:
              properties:
                domain:
                  type: string
                is_active:
                  type: boolean
                subject_area:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00'
                  domain: product
                  image_key: null
                  is_active: true
                  slug: checkout
                  subject_area: null
                  term_count: 1
                  terms:
                  - abbreviation: null
                    approved_at: null
                    created_at: '2026-07-17T12:00:00'
                    definition: The step where a customer pays for their cart.
                    do_not_change: false
                    do_not_translate: false
                    entry_uid: b2c3d4e5-1111-2222-3333-444455556666
                    gender: null
                    language: en
                    part_of_speech: noun
                    plural_form: null
                    status: preferred
                    term: Checkout
                    translate_as: null
                    uid: c3d4e5f6-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                    usage_note: null
                  uid: b2c3d4e5-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      domain:
                        type: string
                      image_key:
                        nullable: true
                      is_active:
                        type: boolean
                      slug:
                        type: string
                      subject_area:
                        nullable: true
                      term_count:
                        type: integer
                      terms:
                        items:
                          properties:
                            abbreviation:
                              nullable: true
                            approved_at:
                              nullable: true
                            created_at:
                              type: string
                            definition:
                              type: string
                            do_not_change:
                              type: boolean
                            do_not_translate:
                              type: boolean
                            entry_uid:
                              type: string
                            gender:
                              nullable: true
                            language:
                              type: string
                            part_of_speech:
                              type: string
                            plural_form:
                              nullable: true
                            status:
                              type: string
                            term:
                              type: string
                            translate_as:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                            usage_note:
                              nullable: true
                          type: object
                        type: array
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update entry metadata.
      tags:
      - Standards & Compliance
  /standards/style-rules:
    get:
      description: "Query params (all optional):\n  category, severity, applies_to,\
        \ language"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - applies_to:
                  - wiki
                  - help_center
                  category: voice
                  created_at: '2026-07-17T12:00:00'
                  is_active: true
                  is_language_agnostic: true
                  locale_count: 1
                  name: Use active voice
                  notes: null
                  severity: preferred
                  uid: d4e5f6a7-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        applies_to:
                          items:
                            type: string
                          type: array
                        category:
                          type: string
                        created_at:
                          type: string
                        is_active:
                          type: boolean
                        is_language_agnostic:
                          type: boolean
                        locale_count:
                          type: integer
                        name:
                          type: string
                        notes:
                          nullable: true
                        severity:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List style rules.
      tags:
      - Standards & Compliance
    post:
      description: "Body JSON (required: name, category, severity, description):\n\
        \  name, category, severity, description, example_good, example_bad, applies_to"
      requestBody:
        content:
          application/json:
            example:
              applies_to:
              - wiki
              - help_center
              category: voice
              description: Prefer active voice over passive.
              example_bad: An email is sent by the system.
              example_good: The system sends an email.
              name: Use active voice
              severity: preferred
            schema:
              properties:
                applies_to:
                  items:
                    type: string
                  type: array
                category:
                  type: string
                description:
                  type: string
                example_bad:
                  type: string
                example_good:
                  type: string
                name:
                  type: string
                severity:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  applies_to:
                  - wiki
                  - help_center
                  category: voice
                  created_at: '2026-07-17T12:00:00'
                  is_active: true
                  is_language_agnostic: true
                  locale_count: 1
                  locales:
                  - created_at: '2026-07-17T12:00:00'
                    description: Prefer active voice over passive.
                    example_bad: An email is sent by the system.
                    example_good: The system sends an email.
                    is_disabled: false
                    language: en
                    locale_notes: null
                    rule_uid: d4e5f6a7-1111-2222-3333-444455556666
                    severity_override: null
                    uid: e5f6a7b8-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                  name: Use active voice
                  notes: null
                  severity: preferred
                  uid: d4e5f6a7-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      applies_to:
                        items:
                          type: string
                        type: array
                      category:
                        type: string
                      created_at:
                        type: string
                      is_active:
                        type: boolean
                      is_language_agnostic:
                        type: boolean
                      locale_count:
                        type: integer
                      locales:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            example_bad:
                              type: string
                            example_good:
                              type: string
                            is_disabled:
                              type: boolean
                            language:
                              type: string
                            locale_notes:
                              nullable: true
                            rule_uid:
                              type: string
                            severity_override:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      name:
                        type: string
                      notes:
                        nullable: true
                      severity:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a style rule.
      tags:
      - Standards & Compliance
  /standards/style-rules/{rule_uid}:
    delete:
      parameters:
      - in: path
        name: rule_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a style rule.
      tags:
      - Standards & Compliance
    get:
      parameters:
      - in: path
        name: rule_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  applies_to:
                  - wiki
                  - help_center
                  category: voice
                  created_at: '2026-07-17T12:00:00'
                  is_active: true
                  is_language_agnostic: true
                  locale_count: 1
                  locales:
                  - created_at: '2026-07-17T12:00:00'
                    description: Prefer active voice over passive.
                    example_bad: An email is sent by the system.
                    example_good: The system sends an email.
                    is_disabled: false
                    language: en
                    locale_notes: null
                    rule_uid: d4e5f6a7-1111-2222-3333-444455556666
                    severity_override: null
                    uid: e5f6a7b8-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                  name: Use active voice
                  notes: null
                  severity: preferred
                  uid: d4e5f6a7-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      applies_to:
                        items:
                          type: string
                        type: array
                      category:
                        type: string
                      created_at:
                        type: string
                      is_active:
                        type: boolean
                      is_language_agnostic:
                        type: boolean
                      locale_count:
                        type: integer
                      locales:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            example_bad:
                              type: string
                            example_good:
                              type: string
                            is_disabled:
                              type: boolean
                            language:
                              type: string
                            locale_notes:
                              nullable: true
                            rule_uid:
                              type: string
                            severity_override:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      name:
                        type: string
                      notes:
                        nullable: true
                      severity:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get rule with all locales.
      tags:
      - Standards & Compliance
    patch:
      description: "Body JSON (all optional):\n  name, category, severity, applies_to,\
        \ notes, is_active"
      parameters:
      - in: path
        name: rule_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              applies_to:
              - wiki
              category: voice
              is_active: true
              name: Use active voice
              notes: Applies to all docs
              severity: required
            schema:
              properties:
                applies_to:
                  items:
                    type: string
                  type: array
                category:
                  type: string
                is_active:
                  type: boolean
                name:
                  type: string
                notes:
                  type: string
                severity:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  applies_to:
                  - wiki
                  - help_center
                  category: voice
                  created_at: '2026-07-17T12:00:00'
                  is_active: true
                  is_language_agnostic: true
                  locale_count: 1
                  locales:
                  - created_at: '2026-07-17T12:00:00'
                    description: Prefer active voice over passive.
                    example_bad: An email is sent by the system.
                    example_good: The system sends an email.
                    is_disabled: false
                    language: en
                    locale_notes: null
                    rule_uid: d4e5f6a7-1111-2222-3333-444455556666
                    severity_override: null
                    uid: e5f6a7b8-1111-2222-3333-444455556666
                    updated_at: '2026-07-17T12:00:00'
                  name: Use active voice
                  notes: null
                  severity: preferred
                  uid: d4e5f6a7-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
              schema:
                properties:
                  data:
                    properties:
                      applies_to:
                        items:
                          type: string
                        type: array
                      category:
                        type: string
                      created_at:
                        type: string
                      is_active:
                        type: boolean
                      is_language_agnostic:
                        type: boolean
                      locale_count:
                        type: integer
                      locales:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            example_bad:
                              type: string
                            example_good:
                              type: string
                            is_disabled:
                              type: boolean
                            language:
                              type: string
                            locale_notes:
                              nullable: true
                            rule_uid:
                              type: string
                            severity_override:
                              nullable: true
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      name:
                        type: string
                      notes:
                        nullable: true
                      severity:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a style rule.
      tags:
      - Standards & Compliance
  /strings/filter-templates:
    get:
      description: "Query params:\n  format  — filter by file format (json, xml, csv,\
        \ …)"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - config:
                    strip_html: true
                    translate_paths:
                    - i18n.*
                  created_at: '2026-07-17T12:00:00'
                  created_by: user@example.com
                  description: Extracts values under i18n.* keys
                  disabled_at: null
                  disabled_by: null
                  format: json
                  name: JSON translatable strings
                  status: testing
                  uid: a1b2c3d4-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  updated_by: null
              schema:
                properties:
                  data:
                    items:
                      properties:
                        config:
                          properties:
                            strip_html:
                              type: boolean
                            translate_paths:
                              items:
                                type: string
                              type: array
                          type: object
                        created_at:
                          type: string
                        created_by:
                          type: string
                        description:
                          type: string
                        disabled_at:
                          nullable: true
                        disabled_by:
                          nullable: true
                        format:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                        updated_by:
                          nullable: true
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List filter templates.
      tags:
      - String Manager
    post:
      description: "Body JSON:\n  name        string  required\n  format      string\
        \  required  (json|xml|csv|yaml|html|properties|toml)\n  description string\
        \  optional\n  config      object  optional"
      requestBody:
        content:
          application/json:
            example:
              config:
                translate_paths:
                - i18n.*
              description: Extracts values under i18n.* keys
              format: json
              name: JSON translatable strings
            schema:
              properties:
                config:
                  properties:
                    translate_paths:
                      items:
                        type: string
                      type: array
                  type: object
                description:
                  type: string
                format:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  config:
                    strip_html: true
                    translate_paths:
                    - i18n.*
                  created_at: '2026-07-17T12:00:00'
                  created_by: user@example.com
                  description: Extracts values under i18n.* keys
                  disabled_at: null
                  disabled_by: null
                  format: json
                  name: JSON translatable strings
                  status: testing
                  uid: a1b2c3d4-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  updated_by: null
              schema:
                properties:
                  data:
                    properties:
                      config:
                        properties:
                          strip_html:
                            type: boolean
                          translate_paths:
                            items:
                              type: string
                            type: array
                        type: object
                      created_at:
                        type: string
                      created_by:
                        type: string
                      description:
                        type: string
                      disabled_at:
                        nullable: true
                      disabled_by:
                        nullable: true
                      format:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      updated_by:
                        nullable: true
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a filter template.
      tags:
      - String Manager
  /strings/filter-templates/{template_uid}:
    delete:
      parameters:
      - in: path
        name: template_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a filter template.
      tags:
      - String Manager
    get:
      parameters:
      - in: path
        name: template_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  config:
                    strip_html: true
                    translate_paths:
                    - i18n.*
                  created_at: '2026-07-17T12:00:00'
                  created_by: user@example.com
                  description: Extracts values under i18n.* keys
                  disabled_at: null
                  disabled_by: null
                  format: json
                  name: JSON translatable strings
                  status: testing
                  uid: a1b2c3d4-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  updated_by: null
              schema:
                properties:
                  data:
                    properties:
                      config:
                        properties:
                          strip_html:
                            type: boolean
                          translate_paths:
                            items:
                              type: string
                            type: array
                        type: object
                      created_at:
                        type: string
                      created_by:
                        type: string
                      description:
                        type: string
                      disabled_at:
                        nullable: true
                      disabled_by:
                        nullable: true
                      format:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      updated_by:
                        nullable: true
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a filter template.
      tags:
      - String Manager
    patch:
      description: "Body JSON (all fields optional):\n  name, description, format,\
        \ config"
      parameters:
      - in: path
        name: template_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              config:
                strip_html: true
              description: Updated
              format: json
              name: JSON translatable strings v2
            schema:
              properties:
                config:
                  properties:
                    strip_html:
                      type: boolean
                  type: object
                description:
                  type: string
                format:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  config:
                    strip_html: true
                    translate_paths:
                    - i18n.*
                  created_at: '2026-07-17T12:00:00'
                  created_by: user@example.com
                  description: Extracts values under i18n.* keys
                  disabled_at: null
                  disabled_by: null
                  format: json
                  name: JSON translatable strings
                  status: testing
                  uid: a1b2c3d4-1111-2222-3333-444455556666
                  updated_at: '2026-07-17T12:00:00'
                  updated_by: null
              schema:
                properties:
                  data:
                    properties:
                      config:
                        properties:
                          strip_html:
                            type: boolean
                          translate_paths:
                            items:
                              type: string
                            type: array
                        type: object
                      created_at:
                        type: string
                      created_by:
                        type: string
                      description:
                        type: string
                      disabled_at:
                        nullable: true
                      disabled_by:
                        nullable: true
                      format:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                      updated_by:
                        nullable: true
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a filter template.
      tags:
      - String Manager
  /support/tickets:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  tickets:
                  - assignee:
                      id: 4
                      name: Ada Lovelace
                    contact:
                      email: jordan@acme.com
                      id: 22
                      name: Jordan Lee
                    created_at: '2026-07-17T12:00:00+00:00'
                    first_response_at: '2026-07-17T12:05:00+00:00'
                    id: 812
                    mailbox_id: 3
                    message_count: 2
                    number: 1043
                    resolved_at: null
                    severity: high
                    source: api
                    status: open
                    subject: Login page returns 500
                    uid: tkt_9f3a2b
                    updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      tickets:
                        items:
                          properties:
                            assignee:
                              properties:
                                id:
                                  type: integer
                                name:
                                  type: string
                              type: object
                            contact:
                              properties:
                                email:
                                  type: string
                                id:
                                  type: integer
                                name:
                                  type: string
                              type: object
                            created_at:
                              type: string
                            first_response_at:
                              type: string
                            id:
                              type: integer
                            mailbox_id:
                              type: integer
                            message_count:
                              type: integer
                            number:
                              type: integer
                            resolved_at:
                              nullable: true
                            severity:
                              type: string
                            source:
                              type: string
                            status:
                              type: string
                            subject:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'List tickets. Query: ?status= ?severity= ?limit= (default 50, max
        200) ?offset=.'
      tags:
      - Support
    post:
      description: 'Body (JSON): { subject (req), body (req), contact_email?, contact_name?,

        severity? (low|normal|high|urgent|critical), mailbox_id? }.'
      requestBody:
        content:
          application/json:
            example:
              body: Users cannot sign in this morning.
              contact_email: jordan@acme.com
              contact_name: Jordan Lee
              mailbox_id: 3
              severity: high
              subject: Login page returns 500
            schema:
              properties:
                body:
                  type: string
                contact_email:
                  type: string
                contact_name:
                  type: string
                mailbox_id:
                  type: integer
                severity:
                  type: string
                subject:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 4
                    name: Ada Lovelace
                  contact:
                    email: jordan@acme.com
                    id: 22
                    name: Jordan Lee
                  created_at: '2026-07-17T12:00:00+00:00'
                  first_response_at: '2026-07-17T12:05:00+00:00'
                  id: 812
                  mailbox_id: 3
                  message_count: 2
                  messages:
                  - body_html: <p>Thanks for reaching out — we are on it.</p>
                    body_text: Thanks for reaching out — we are on it.
                    created_at: '2026-07-17T12:05:00+00:00'
                    id: 5012
                    is_note: false
                    sender: Ada Lovelace
                    sender_email: ada@acme.com
                    sender_type: agent
                  number: 1043
                  resolved_at: null
                  severity: high
                  source: api
                  status: open
                  subject: Login page returns 500
                  uid: tkt_9f3a2b
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      contact:
                        properties:
                          email:
                            type: string
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      created_at:
                        type: string
                      first_response_at:
                        type: string
                      id:
                        type: integer
                      mailbox_id:
                        type: integer
                      message_count:
                        type: integer
                      messages:
                        items:
                          properties:
                            body_html:
                              type: string
                            body_text:
                              type: string
                            created_at:
                              type: string
                            id:
                              type: integer
                            is_note:
                              type: boolean
                            sender:
                              type: string
                            sender_email:
                              type: string
                            sender_type:
                              type: string
                          type: object
                        type: array
                      number:
                        type: integer
                      resolved_at:
                        nullable: true
                      severity:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      subject:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a ticket.
      tags:
      - Support
  /support/tickets/{uid}:
    get:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 4
                    name: Ada Lovelace
                  contact:
                    email: jordan@acme.com
                    id: 22
                    name: Jordan Lee
                  created_at: '2026-07-17T12:00:00+00:00'
                  first_response_at: '2026-07-17T12:05:00+00:00'
                  id: 812
                  mailbox_id: 3
                  message_count: 2
                  messages:
                  - body_html: <p>Thanks for reaching out — we are on it.</p>
                    body_text: Thanks for reaching out — we are on it.
                    created_at: '2026-07-17T12:05:00+00:00'
                    id: 5012
                    is_note: false
                    sender: Ada Lovelace
                    sender_email: ada@acme.com
                    sender_type: agent
                  number: 1043
                  resolved_at: null
                  severity: high
                  source: api
                  status: open
                  subject: Login page returns 500
                  uid: tkt_9f3a2b
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      contact:
                        properties:
                          email:
                            type: string
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      created_at:
                        type: string
                      first_response_at:
                        type: string
                      id:
                        type: integer
                      mailbox_id:
                        type: integer
                      message_count:
                        type: integer
                      messages:
                        items:
                          properties:
                            body_html:
                              type: string
                            body_text:
                              type: string
                            created_at:
                              type: string
                            id:
                              type: integer
                            is_note:
                              type: boolean
                            sender:
                              type: string
                            sender_email:
                              type: string
                            sender_type:
                              type: string
                          type: object
                        type: array
                      number:
                        type: integer
                      resolved_at:
                        nullable: true
                      severity:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      subject:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a ticket with its full message thread.
      tags:
      - Support
  /support/tickets/{uid}/assign:
    post:
      description: 'user id), or { assignee_id: null } to unassign.'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              assignee_id: 4
            schema:
              properties:
                assignee_id:
                  type: integer
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 4
                    name: Ada Lovelace
                  contact:
                    email: jordan@acme.com
                    id: 22
                    name: Jordan Lee
                  created_at: '2026-07-17T12:00:00+00:00'
                  first_response_at: '2026-07-17T12:05:00+00:00'
                  id: 812
                  mailbox_id: 3
                  message_count: 2
                  number: 1043
                  resolved_at: null
                  severity: high
                  source: api
                  status: open
                  subject: Login page returns 500
                  uid: tkt_9f3a2b
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      contact:
                        properties:
                          email:
                            type: string
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      created_at:
                        type: string
                      first_response_at:
                        type: string
                      id:
                        type: integer
                      mailbox_id:
                        type: integer
                      message_count:
                        type: integer
                      number:
                        type: integer
                      resolved_at:
                        nullable: true
                      severity:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      subject:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Assign or unassign a ticket. Body (JSON): { assignee_id } (a workspace'
      tags:
      - Support
  /support/tickets/{uid}/reply:
    post:
      description: 'Body (JSON): { body (req), internal? (bool — internal note, not
        visible to

        the customer), send_email? (bool — actually email the customer; requires a

        mailbox and defaults to false) }.'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: We deployed a fix — please retry and let us know.
              internal: false
              send_email: true
            schema:
              properties:
                body:
                  type: string
                internal:
                  type: boolean
                send_email:
                  type: boolean
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  body_html: <p>Thanks for reaching out — we are on it.</p>
                  body_text: Thanks for reaching out — we are on it.
                  created_at: '2026-07-17T12:05:00+00:00'
                  id: 5012
                  is_note: false
                  sender: Ada Lovelace
                  sender_email: ada@acme.com
                  sender_type: agent
              schema:
                properties:
                  data:
                    properties:
                      body_html:
                        type: string
                      body_text:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: integer
                      is_note:
                        type: boolean
                      sender:
                        type: string
                      sender_email:
                        type: string
                      sender_type:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add a reply (or internal note) to a ticket.
      tags:
      - Support
  /support/tickets/{uid}/severity:
    post:
      description: 'One of: low, normal, high, urgent, critical.'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              severity: urgent
            schema:
              properties:
                severity:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 4
                    name: Ada Lovelace
                  contact:
                    email: jordan@acme.com
                    id: 22
                    name: Jordan Lee
                  created_at: '2026-07-17T12:00:00+00:00'
                  first_response_at: '2026-07-17T12:05:00+00:00'
                  id: 812
                  mailbox_id: 3
                  message_count: 2
                  number: 1043
                  resolved_at: null
                  severity: high
                  source: api
                  status: open
                  subject: Login page returns 500
                  uid: tkt_9f3a2b
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      contact:
                        properties:
                          email:
                            type: string
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      created_at:
                        type: string
                      first_response_at:
                        type: string
                      id:
                        type: integer
                      mailbox_id:
                        type: integer
                      message_count:
                        type: integer
                      number:
                        type: integer
                      resolved_at:
                        nullable: true
                      severity:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      subject:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Change ticket severity. Body (JSON): { severity }.'
      tags:
      - Support
  /support/tickets/{uid}/status:
    post:
      description: 'One of: new, open, pending, on_hold, resolved, closed.'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              status: resolved
            schema:
              properties:
                status:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee:
                    id: 4
                    name: Ada Lovelace
                  contact:
                    email: jordan@acme.com
                    id: 22
                    name: Jordan Lee
                  created_at: '2026-07-17T12:00:00+00:00'
                  first_response_at: '2026-07-17T12:05:00+00:00'
                  id: 812
                  mailbox_id: 3
                  message_count: 2
                  number: 1043
                  resolved_at: null
                  severity: high
                  source: api
                  status: open
                  subject: Login page returns 500
                  uid: tkt_9f3a2b
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      assignee:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      contact:
                        properties:
                          email:
                            type: string
                          id:
                            type: integer
                          name:
                            type: string
                        type: object
                      created_at:
                        type: string
                      first_response_at:
                        type: string
                      id:
                        type: integer
                      mailbox_id:
                        type: integer
                      message_count:
                        type: integer
                      number:
                        type: integer
                      resolved_at:
                        nullable: true
                      severity:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      subject:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Change ticket status. Body (JSON): { status }.'
      tags:
      - Support
  /surveys:
    get:
      description: Returns paginated list of surveys. Filter by `?status=draft|active|closed`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - draft
          - active
          - closed
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Survey'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List surveys
      tags:
      - Surveys
    post:
      description: Creates a new survey with status `draft`. Add questions next.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create survey
      tags:
      - Surveys
  /surveys/{survey_id}:
    delete:
      description: Permanently delete a survey and all its responses.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete survey
      tags:
      - Surveys
    get:
      description: Retrieve a single survey by ID.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get survey
      tags:
      - Surveys
    patch:
      description: Update survey metadata. Pass only fields to change.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update survey
      tags:
      - Surveys
  /surveys/{survey_id}/close:
    post:
      description: Stop accepting responses for a live survey.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Close survey
      tags:
      - Surveys
  /surveys/{survey_id}/publish:
    post:
      description: Make a draft survey live. Survey must have at least one question.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Survey'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Publish survey
      tags:
      - Surveys
  /surveys/{survey_id}/questions:
    get:
      description: Get all questions for a survey, in display order.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Question'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List questions
      tags:
      - Surveys
    post:
      description: Add a new question to a survey.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Question'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add question
      tags:
      - Surveys
  /surveys/{survey_id}/responses:
    get:
      description: Get paginated list of survey responses with answers.
      parameters:
      - in: path
        name: survey_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Response'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List responses
      tags:
      - Surveys
  /task-lists:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#6b7280'
                  icon: bi-list-task
                  name: Work
                  open_task_count: 5
                  position: 0
                  uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        icon:
                          type: string
                        name:
                          type: string
                        open_task_count:
                          type: integer
                        position:
                          type: integer
                        uid:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all personal task lists for the current user.
      tags:
      - Project Manager
    post:
      description: "Body:\n  name   string  required\n  color  string  hex color (optional,\
        \ default #6b7280)\n  icon   string  Bootstrap Icons class (optional)"
      requestBody:
        content:
          application/json:
            example:
              color: '#6b7280'
              icon: bi-list-task
              name: Work
            schema:
              properties:
                color:
                  type: string
                icon:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#6b7280'
                  icon: bi-list-task
                  name: Work
                  open_task_count: 5
                  position: 0
                  uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      icon:
                        type: string
                      name:
                        type: string
                      open_task_count:
                        type: integer
                      position:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a task list.
      tags:
      - Project Manager
  /task-lists/{uid}:
    delete:
      description: (list_id set to NULL) rather than deleted.
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ok: true
              schema:
                properties:
                  data:
                    properties:
                      ok:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a task list.  All tasks in the list are moved to the Inbox
      tags:
      - Project Manager
    patch:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              color: '#2563eb'
              icon: bi-briefcase
              name: Work (2026)
            schema:
              properties:
                color:
                  type: string
                icon:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#6b7280'
                  icon: bi-list-task
                  name: Work
                  open_task_count: 5
                  position: 0
                  uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      icon:
                        type: string
                      name:
                        type: string
                      open_task_count:
                        type: integer
                      position:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a task list's name, color, or icon.
      tags:
      - Project Manager
  /tasks:
    get:
      description: "Query params:\n  status      open | completed | archived | all\
        \  (default: open)\n  priority    1-4 (optional filter)\n  list_uid    filter\
        \ by task list UUID (pass 'inbox' for un-listed tasks)\n  due_today   true\
        \ → only tasks where due_date = today\n  since       ISO datetime — only tasks\
        \ updated after this (incremental sync)\n  limit       default 100, max 500\n\
        \  offset      default 0"
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  items:
                  - completed_at: null
                    created_at: '2026-07-17T12:00:00+00:00'
                    due_date: '2026-07-20'
                    due_time: 09:00:00
                    list_name: Work
                    list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                    notes: Include revenue charts
                    position: 0
                    priority: 2
                    priority_color: '#ea580c'
                    priority_label: P2
                    recurrence: null
                    status: open
                    subtask_count: 2
                    tags:
                    - color: '#ef4444'
                      name: urgent
                      uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                    title: Prepare Q3 report
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    updated_at: '2026-07-17T12:05:00+00:00'
                  limit: 100
                  offset: 0
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            completed_at:
                              nullable: true
                            created_at:
                              type: string
                            due_date:
                              type: string
                            due_time:
                              type: string
                            list_name:
                              type: string
                            list_uid:
                              type: string
                            notes:
                              type: string
                            position:
                              type: integer
                            priority:
                              type: integer
                            priority_color:
                              type: string
                            priority_label:
                              type: string
                            recurrence:
                              nullable: true
                            status:
                              type: string
                            subtask_count:
                              type: integer
                            tags:
                              items:
                                properties:
                                  color:
                                    type: string
                                  name:
                                    type: string
                                  uid:
                                    type: string
                                type: object
                              type: array
                            title:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List personal tasks for the current user.
      tags:
      - Project Manager
    post:
      description: "Body:\n  title      string  required\n  notes      string  optional\n\
        \  priority   int     1-4 (default 4)\n  due_date   string  YYYY-MM-DD (optional)\n\
        \  list_uid   string  task list UUID (optional; null = Inbox)\n  tags    \
        \   array   tag name strings (optional)"
      requestBody:
        content:
          application/json:
            example:
              due_date: '2026-07-20'
              list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              notes: Include revenue charts
              priority: 2
              tags:
              - urgent
              title: Prepare Q3 report
            schema:
              properties:
                due_date:
                  type: string
                list_uid:
                  type: string
                notes:
                  type: string
                priority:
                  type: integer
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: Include revenue charts
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 2
                  tags:
                  - color: '#ef4444'
                    name: urgent
                    uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  title: Prepare Q3 report
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        nullable: true
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        type: string
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      tags:
                        items:
                          properties:
                            color:
                              type: string
                            name:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a personal task.
      tags:
      - Project Manager
  /tasks/{uid}:
    delete:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ok: true
              schema:
                properties:
                  data:
                    properties:
                      ok:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Permanently delete a task.
      tags:
      - Project Manager
    get:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: Include revenue charts
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 2
                  subtasks:
                  - completed_at: null
                    created_at: '2026-07-17T12:00:00+00:00'
                    due_date: '2026-07-20'
                    due_time: 09:00:00
                    list_name: Work
                    list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                    notes: null
                    position: 0
                    priority: 2
                    priority_color: '#ea580c'
                    priority_label: P2
                    recurrence: null
                    status: open
                    subtask_count: 0
                    tags: []
                    title: Draft the outline
                    uid: d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70
                    updated_at: '2026-07-17T12:05:00+00:00'
                  tags:
                  - color: '#ef4444'
                    name: urgent
                    uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  title: Prepare Q3 report
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        nullable: true
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        type: string
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      subtasks:
                        items:
                          properties:
                            completed_at:
                              nullable: true
                            created_at:
                              type: string
                            due_date:
                              type: string
                            due_time:
                              type: string
                            list_name:
                              type: string
                            list_uid:
                              type: string
                            notes:
                              nullable: true
                            position:
                              type: integer
                            priority:
                              type: integer
                            priority_color:
                              type: string
                            priority_label:
                              type: string
                            recurrence:
                              nullable: true
                            status:
                              type: string
                            subtask_count:
                              type: integer
                            tags:
                              items: {}
                              type: array
                            title:
                              type: string
                            uid:
                              type: string
                            updated_at:
                              type: string
                          type: object
                        type: array
                      tags:
                        items:
                          properties:
                            color:
                              type: string
                            name:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a single task including subtasks.
      tags:
      - Project Manager
    patch:
      description: 'Accepted body keys: title, notes, priority, due_date, list_uid,
        tags, status'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              priority: 1
              status: open
              tags:
              - urgent
              - finance
              title: Prepare Q3 report (final)
            schema:
              properties:
                priority:
                  type: integer
                status:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: Include revenue charts
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 2
                  tags:
                  - color: '#ef4444'
                    name: urgent
                    uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  title: Prepare Q3 report
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        nullable: true
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        type: string
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      tags:
                        items:
                          properties:
                            color:
                              type: string
                            name:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a task's fields.
      tags:
      - Project Manager
  /tasks/{uid}/attachments:
    get:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - file_size: 284120
                  mime_type: application/pdf
                  original_filename: spec.pdf
                  uid: f6a7b8c9-d0e1-4f2a-8b3c-4d5e6f7a8b9c
                  uploaded_at: '2026-07-17T12:12:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        file_size:
                          type: integer
                        mime_type:
                          type: string
                        original_filename:
                          type: string
                        uid:
                          type: string
                        uploaded_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all attachments on a task, ordered by upload date.
      tags:
      - Project Manager
    post:
      description: "Request: multipart/form-data\n  file  binary  required  (max 25\
        \ MB)"
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  file_size: 284120
                  mime_type: application/pdf
                  original_filename: spec.pdf
                  uid: f6a7b8c9-d0e1-4f2a-8b3c-4d5e6f7a8b9c
                  uploaded_at: '2026-07-17T12:12:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      file_size:
                        type: integer
                      mime_type:
                        type: string
                      original_filename:
                        type: string
                      uid:
                        type: string
                      uploaded_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Upload a file attachment to a task.
      tags:
      - Project Manager
  /tasks/{uid}/attachments/{att_uid}:
    delete:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      - in: path
        name: att_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ok: true
              schema:
                properties:
                  data:
                    properties:
                      ok:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete an attachment from storage and the database.
      tags:
      - Project Manager
  /tasks/{uid}/attachments/{att_uid}/download:
    get:
      description: 'Local storage: streams the file directly.

        S3 storage: returns a 302 redirect to a 5-minute presigned URL.'
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      - in: path
        name: att_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    additionalProperties: true
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Download an attachment.
      tags:
      - Project Manager
  /tasks/{uid}/comments:
    get:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - body: Looks good, ship it.
                  created_at: '2026-07-17T12:10:00+00:00'
                  uid: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
                  updated_at: '2026-07-17T12:10:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        body:
                          type: string
                        created_at:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all comments on a task, ordered oldest-first.
      tags:
      - Project Manager
    post:
      description: "Body:\n  body  string  required"
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Looks good, ship it.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  body: Looks good, ship it.
                  created_at: '2026-07-17T12:10:00+00:00'
                  uid: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
                  updated_at: '2026-07-17T12:10:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      body:
                        type: string
                      created_at:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Add a comment to a task.
      tags:
      - Project Manager
  /tasks/{uid}/comments/{comment_uid}:
    delete:
      parameters:
      - in: path
        name: comment_uid
        required: true
        schema:
          type: string
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ok: true
              schema:
                properties:
                  data:
                    properties:
                      ok:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a comment.
      tags:
      - Project Manager
    patch:
      description: "Body:\n  body  string  required"
      parameters:
      - in: path
        name: comment_uid
        required: true
        schema:
          type: string
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Actually, hold off until Friday.
            schema:
              properties:
                body:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  body: Looks good, ship it.
                  created_at: '2026-07-17T12:10:00+00:00'
                  uid: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
                  updated_at: '2026-07-17T12:10:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      body:
                        type: string
                      created_at:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Edit a comment's text.
      tags:
      - Project Manager
  /tasks/{uid}/complete:
    post:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed_at: '2026-07-17T13:00:00+00:00'
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: Include revenue charts
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: completed
                  subtask_count: 2
                  tags:
                  - color: '#ef4444'
                    name: urgent
                    uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  title: Prepare Q3 report
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        type: string
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        type: string
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      tags:
                        items:
                          properties:
                            color:
                              type: string
                            name:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Mark a task as completed.
      tags:
      - Project Manager
  /tasks/{uid}/reopen:
    post:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: Include revenue charts
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 2
                  tags:
                  - color: '#ef4444'
                    name: urgent
                    uid: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  title: Prepare Q3 report
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        nullable: true
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        type: string
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      tags:
                        items:
                          properties:
                            color:
                              type: string
                            name:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Reopen a completed or archived task.
      tags:
      - Project Manager
  /tasks/{uid}/subtasks:
    get:
      description: "Query params:\n  status  open | completed | archived | all  (default:\
        \ all)"
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: null
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 0
                  tags: []
                  title: Draft the outline
                  uid: d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    items:
                      properties:
                        completed_at:
                          nullable: true
                        created_at:
                          type: string
                        due_date:
                          type: string
                        due_time:
                          type: string
                        list_name:
                          type: string
                        list_uid:
                          type: string
                        notes:
                          nullable: true
                        position:
                          type: integer
                        priority:
                          type: integer
                        priority_color:
                          type: string
                        priority_label:
                          type: string
                        recurrence:
                          nullable: true
                        status:
                          type: string
                        subtask_count:
                          type: integer
                        tags:
                          items: {}
                          type: array
                        title:
                          type: string
                        uid:
                          type: string
                        updated_at:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all subtasks of a parent task.
      tags:
      - Project Manager
    post:
      description: "Body:\n  title     string  required\n  notes     string  optional\n\
        \  priority  int     1-4 (default 4 = Low)\n  due_date  string  YYYY-MM-DD\
        \ (optional)"
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              due_date: '2026-07-18'
              notes: null
              priority: 4
              title: Draft the outline
            schema:
              properties:
                due_date:
                  type: string
                notes:
                  nullable: true
                priority:
                  type: integer
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  completed_at: null
                  created_at: '2026-07-17T12:00:00+00:00'
                  due_date: '2026-07-20'
                  due_time: 09:00:00
                  list_name: Work
                  list_uid: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  notes: null
                  position: 0
                  priority: 2
                  priority_color: '#ea580c'
                  priority_label: P2
                  recurrence: null
                  status: open
                  subtask_count: 0
                  tags: []
                  title: Draft the outline
                  uid: d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70
                  updated_at: '2026-07-17T12:05:00+00:00'
              schema:
                properties:
                  data:
                    properties:
                      completed_at:
                        nullable: true
                      created_at:
                        type: string
                      due_date:
                        type: string
                      due_time:
                        type: string
                      list_name:
                        type: string
                      list_uid:
                        type: string
                      notes:
                        nullable: true
                      position:
                        type: integer
                      priority:
                        type: integer
                      priority_color:
                        type: string
                      priority_label:
                        type: string
                      recurrence:
                        nullable: true
                      status:
                        type: string
                      subtask_count:
                        type: integer
                      tags:
                        items: {}
                        type: array
                      title:
                        type: string
                      uid:
                        type: string
                      updated_at:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a subtask under the given parent task.
      tags:
      - Project Manager
  /timetracking/entries:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  items:
                  - bill_rate: 120
                    created_at: '2026-07-17T10:30:00+00:00'
                    description: Homepage mockups
                    duration_minutes: 90
                    editable: true
                    ended_at: '2026-07-17T10:30:00+00:00'
                    is_billable: true
                    is_running: false
                    locked: false
                    logged_date: '2026-07-17'
                    project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                    project_name: Website Redesign
                    source: manual
                    started_at: '2026-07-17T09:00:00+00:00'
                    task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                    uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  limit: 50
                  offset: 0
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            bill_rate:
                              type: number
                            created_at:
                              type: string
                            description:
                              type: string
                            duration_minutes:
                              type: integer
                            editable:
                              type: boolean
                            ended_at:
                              type: string
                            is_billable:
                              type: boolean
                            is_running:
                              type: boolean
                            locked:
                              type: boolean
                            logged_date:
                              type: string
                            project_id:
                              type: string
                            project_name:
                              type: string
                            source:
                              type: string
                            started_at:
                              type: string
                            task_id:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get timetracking entries
      tags:
      - Time Tracking
    post:
      requestBody:
        content:
          application/json:
            example:
              description: Homepage mockups
              duration_minutes: 90
              is_billable: true
              logged_date: '2026-07-17'
              project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
            schema:
              properties:
                description:
                  type: string
                duration_minutes:
                  type: integer
                is_billable:
                  type: boolean
                logged_date:
                  type: string
                project_id:
                  type: string
                task_id:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  bill_rate: 120
                  created_at: '2026-07-17T10:30:00+00:00'
                  description: Homepage mockups
                  duration_minutes: 90
                  editable: true
                  ended_at: '2026-07-17T10:30:00+00:00'
                  is_billable: true
                  is_running: false
                  locked: false
                  logged_date: '2026-07-17'
                  project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  project_name: Website Redesign
                  source: manual
                  started_at: '2026-07-17T09:00:00+00:00'
                  task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      bill_rate:
                        type: number
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_minutes:
                        type: integer
                      editable:
                        type: boolean
                      ended_at:
                        type: string
                      is_billable:
                        type: boolean
                      is_running:
                        type: boolean
                      locked:
                        type: boolean
                      logged_date:
                        type: string
                      project_id:
                        type: string
                      project_name:
                        type: string
                      source:
                        type: string
                      started_at:
                        type: string
                      task_id:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create timetracking entries
      tags:
      - Time Tracking
  /timetracking/entries/{uid}:
    delete:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete timetracking entries uid
      tags:
      - Time Tracking
    patch:
      parameters:
      - in: path
        name: uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: Homepage + about page mockups
              duration_minutes: 120
              is_billable: true
            schema:
              properties:
                description:
                  type: string
                duration_minutes:
                  type: integer
                is_billable:
                  type: boolean
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  bill_rate: 120
                  created_at: '2026-07-17T10:30:00+00:00'
                  description: Homepage mockups
                  duration_minutes: 90
                  editable: true
                  ended_at: '2026-07-17T10:30:00+00:00'
                  is_billable: true
                  is_running: false
                  locked: false
                  logged_date: '2026-07-17'
                  project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  project_name: Website Redesign
                  source: manual
                  started_at: '2026-07-17T09:00:00+00:00'
                  task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      bill_rate:
                        type: number
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_minutes:
                        type: integer
                      editable:
                        type: boolean
                      ended_at:
                        type: string
                      is_billable:
                        type: boolean
                      is_running:
                        type: boolean
                      locked:
                        type: boolean
                      logged_date:
                        type: string
                      project_id:
                        type: string
                      project_name:
                        type: string
                      source:
                        type: string
                      started_at:
                        type: string
                      task_id:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update timetracking entries uid
      tags:
      - Time Tracking
  /timetracking/projects:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  items:
                  - color: '#2563eb'
                    id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                    is_billable: true
                    name: Website Redesign
                    tasks:
                    - id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                      name: Homepage
                  total: 1
              schema:
                properties:
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            color:
                              type: string
                            id:
                              type: string
                            is_billable:
                              type: boolean
                            name:
                              type: string
                            tasks:
                              items:
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                type: object
                              type: array
                          type: object
                        type: array
                      total:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get timetracking projects
      tags:
      - Time Tracking
  /timetracking/timer:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  bill_rate: 120
                  created_at: '2026-07-17T10:30:00+00:00'
                  description: Homepage mockups
                  duration_minutes: 12
                  editable: true
                  ended_at: null
                  is_billable: true
                  is_running: true
                  locked: false
                  logged_date: '2026-07-17'
                  project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  project_name: Website Redesign
                  source: manual
                  started_at: '2026-07-17T09:00:00+00:00'
                  task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      bill_rate:
                        type: number
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_minutes:
                        type: integer
                      editable:
                        type: boolean
                      ended_at:
                        nullable: true
                      is_billable:
                        type: boolean
                      is_running:
                        type: boolean
                      locked:
                        type: boolean
                      logged_date:
                        type: string
                      project_id:
                        type: string
                      project_name:
                        type: string
                      source:
                        type: string
                      started_at:
                        type: string
                      task_id:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get timetracking timer
      tags:
      - Time Tracking
  /timetracking/timer/start:
    post:
      requestBody:
        content:
          application/json:
            example:
              description: Homepage mockups
              project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
            schema:
              properties:
                description:
                  type: string
                project_id:
                  type: string
                task_id:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  bill_rate: 120
                  created_at: '2026-07-17T10:30:00+00:00'
                  description: Homepage mockups
                  duration_minutes: 12
                  editable: true
                  ended_at: null
                  is_billable: true
                  is_running: true
                  locked: false
                  logged_date: '2026-07-17'
                  project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  project_name: Website Redesign
                  source: manual
                  started_at: '2026-07-17T09:00:00+00:00'
                  task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      bill_rate:
                        type: number
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_minutes:
                        type: integer
                      editable:
                        type: boolean
                      ended_at:
                        nullable: true
                      is_billable:
                        type: boolean
                      is_running:
                        type: boolean
                      locked:
                        type: boolean
                      logged_date:
                        type: string
                      project_id:
                        type: string
                      project_name:
                        type: string
                      source:
                        type: string
                      started_at:
                        type: string
                      task_id:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create timetracking timer start
      tags:
      - Time Tracking
  /timetracking/timer/stop:
    post:
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: JSON body — see the endpoint description for accepted fields.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  bill_rate: 120
                  created_at: '2026-07-17T10:30:00+00:00'
                  description: Homepage mockups
                  duration_minutes: 90
                  editable: true
                  ended_at: '2026-07-17T10:30:00+00:00'
                  is_billable: true
                  is_running: false
                  locked: false
                  logged_date: '2026-07-17'
                  project_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  project_name: Website Redesign
                  source: manual
                  started_at: '2026-07-17T09:00:00+00:00'
                  task_id: c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f
                  uid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      bill_rate:
                        type: number
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_minutes:
                        type: integer
                      editable:
                        type: boolean
                      ended_at:
                        type: string
                      is_billable:
                        type: boolean
                      is_running:
                        type: boolean
                      locked:
                        type: boolean
                      logged_date:
                        type: string
                      project_id:
                        type: string
                      project_name:
                        type: string
                      source:
                        type: string
                      started_at:
                        type: string
                      task_id:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create timetracking timer stop
      tags:
      - Time Tracking
  /timetracking/timesheet:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  approved_at: null
                  billable_minutes: 360
                  period_end: '2026-07-19'
                  period_start: '2026-07-13'
                  reject_reason: null
                  status: open
                  submitted_at: null
                  total_minutes: 480
                  uid: d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70
              schema:
                properties:
                  data:
                    properties:
                      approved_at:
                        nullable: true
                      billable_minutes:
                        type: integer
                      period_end:
                        type: string
                      period_start:
                        type: string
                      reject_reason:
                        nullable: true
                      status:
                        type: string
                      submitted_at:
                        nullable: true
                      total_minutes:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get timetracking timesheet
      tags:
      - Time Tracking
  /timetracking/timesheet/submit:
    post:
      requestBody:
        content:
          application/json:
            example:
              date: '2026-07-17'
            schema:
              properties:
                date:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  approved_at: null
                  billable_minutes: 360
                  period_end: '2026-07-19'
                  period_start: '2026-07-13'
                  reject_reason: null
                  status: submitted
                  submitted_at: '2026-07-17T17:00:00+00:00'
                  total_minutes: 480
                  uid: d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70
              schema:
                properties:
                  data:
                    properties:
                      approved_at:
                        nullable: true
                      billable_minutes:
                        type: integer
                      period_end:
                        type: string
                      period_start:
                        type: string
                      reject_reason:
                        nullable: true
                      status:
                        type: string
                      submitted_at:
                        type: string
                      total_minutes:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create timetracking timesheet submit
      tags:
      - Time Tracking
  /transfers:
    get:
      description: Returns a paginated list of outbound file transfers for this account.
        Filter by `?status=active|revoked|expired`.
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      - in: query
        name: status
        schema:
          enum:
          - active
          - revoked
          - expired
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/FileTransfer'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List transfers
      tags:
      - File Transfer & Requests
    post:
      description: Upload one or more files and create a shareable download link.
        Send as `multipart/form-data` with one or more `files[]` parts. All other
        fields (title, message, recipient_emails, expires_in, max_downloads, password)
        are optional form fields. Recipient notification emails are sent asynchronously
        when `recipient_emails` is provided.
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                expires_in:
                  default: '7'
                  enum:
                  - '1'
                  - '3'
                  - '7'
                  - '14'
                  - '30'
                  - never
                  type: string
                files[]:
                  description: One or more files to upload.
                  items:
                    format: binary
                    type: string
                  type: array
                max_downloads:
                  type: integer
                message:
                  type: string
                password:
                  type: string
                recipient_emails:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileTransfer'
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create transfer
      tags:
      - File Transfer & Requests
  /transfers/{transfer_id}:
    delete:
      description: Revoke (deactivate) a transfer so the download link stops working
        immediately. The files remain stored until the transfer is purged. Pass `?permanent=true`
        to also delete all stored files.
      parameters:
      - in: path
        name: transfer_id
        required: true
        schema:
          type: integer
      - description: If true, permanently delete all stored files.
        in: query
        name: permanent
        schema:
          default: false
          type: boolean
      responses:
        '200':
          description: Revoked or deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Revoke transfer
      tags:
      - File Transfer & Requests
    get:
      description: Retrieve a single transfer by ID, including all files and recipient
        list.
      parameters:
      - in: path
        name: transfer_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileTransfer'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get transfer
      tags:
      - File Transfer & Requests
  /transfers/{transfer_id}/downloads:
    get:
      description: Returns the full download audit log for a transfer — one entry
        per file download (or ZIP download). Includes timestamp and anonymised IP
        address.
      parameters:
      - in: path
        name: transfer_id
        required: true
        schema:
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/TransferDownloadLog'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List download activity
      tags:
      - File Transfer & Requests
  /videohub/projects:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  projects:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    description: Q3 launch recording to caption.
                    duration_ms: 754000
                    primary_language: en-US
                    source_asset_uid: null
                    source_kind: url
                    source_url: https://videos.example.com/keynote.mp4
                    status: active
                    title: Product launch keynote
                    track_count: 2
                    uid: 2f1c8b7e-5a9d-4f21-9b3e-0c7d6a1f4e2b
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      projects:
                        items:
                          properties:
                            created_at:
                              type: string
                            description:
                              type: string
                            duration_ms:
                              type: integer
                            primary_language:
                              type: string
                            source_asset_uid:
                              nullable: true
                            source_kind:
                              type: string
                            source_url:
                              type: string
                            status:
                              type: string
                            title:
                              type: string
                            track_count:
                              type: integer
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List subtitle projects. Optional ?status=active|archived.
      tags:
      - Video Hub
    post:
      requestBody:
        content:
          application/json:
            example:
              description: Q3 launch recording to caption.
              source_url: https://videos.example.com/keynote.mp4
              title: Product launch keynote
            schema:
              properties:
                description:
                  type: string
                source_url:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  description: Q3 launch recording to caption.
                  duration_ms: 754000
                  primary_language: en-US
                  source_asset_uid: null
                  source_kind: url
                  source_url: https://videos.example.com/keynote.mp4
                  status: active
                  title: Product launch keynote
                  track_count: 2
                  uid: 2f1c8b7e-5a9d-4f21-9b3e-0c7d6a1f4e2b
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_ms:
                        type: integer
                      primary_language:
                        type: string
                      source_asset_uid:
                        nullable: true
                      source_kind:
                        type: string
                      source_url:
                        type: string
                      status:
                        type: string
                      title:
                        type: string
                      track_count:
                        type: integer
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Create a project from a video URL. Body: {title, source_url, description?}.'
      tags:
      - Video Hub
  /videohub/projects/{project_uid}:
    get:
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  description: Q3 launch recording to caption.
                  duration_ms: 754000
                  primary_language: en-US
                  source_asset_uid: null
                  source_kind: url
                  source_url: https://videos.example.com/keynote.mp4
                  status: active
                  title: Product launch keynote
                  track_count: 2
                  tracks:
                  - cue_count: 128
                    is_default: true
                    label: English
                    language: en-US
                    source: transcribed
                    status: ready
                    uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
                  uid: 2f1c8b7e-5a9d-4f21-9b3e-0c7d6a1f4e2b
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      description:
                        type: string
                      duration_ms:
                        type: integer
                      primary_language:
                        type: string
                      source_asset_uid:
                        nullable: true
                      source_kind:
                        type: string
                      source_url:
                        type: string
                      status:
                        type: string
                      title:
                        type: string
                      track_count:
                        type: integer
                      tracks:
                        items:
                          properties:
                            cue_count:
                              type: integer
                            is_default:
                              type: boolean
                            label:
                              type: string
                            language:
                              type: string
                            source:
                              type: string
                            status:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a project including its tracks.
      tags:
      - Video Hub
  /videohub/projects/{project_uid}/burns:
    get:
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  burns:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    dub_uid: null
                    duration_ms: 754000
                    error_message: null
                    font_size: medium
                    has_output: false
                    language: en-US
                    onto: source
                    output_mime: null
                    position: bottom
                    provider: mediaconvert
                    status: queued
                    style: outline
                    text_color: FFFFFF
                    track_uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
                    uid: c3d4e5f6-1b2a-4c3d-9e8f-0a1b2c3d4e5f
                  count: 1
              schema:
                properties:
                  data:
                    properties:
                      burns:
                        items:
                          properties:
                            created_at:
                              type: string
                            dub_uid:
                              nullable: true
                            duration_ms:
                              type: integer
                            error_message:
                              nullable: true
                            font_size:
                              type: string
                            has_output:
                              type: boolean
                            language:
                              type: string
                            onto:
                              type: string
                            output_mime:
                              nullable: true
                            position:
                              type: string
                            provider:
                              type: string
                            status:
                              type: string
                            style:
                              type: string
                            text_color:
                              type: string
                            track_uid:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                      count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List a project's subtitle burn-ins (hardcoded-caption renders) + status.
      tags:
      - Video Hub
    post:
      description: font_size?, position?, style?, text_color?}.
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              dub_uid: null
              font_size: medium
              position: bottom
              style: outline
              text_color: FFFFFF
              track_uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
            schema:
              properties:
                dub_uid:
                  nullable: true
                font_size:
                  type: string
                position:
                  type: string
                style:
                  type: string
                text_color:
                  type: string
                track_uid:
                  type: string
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  dub_uid: null
                  duration_ms: 754000
                  error_message: null
                  font_size: medium
                  has_output: false
                  language: en-US
                  onto: source
                  output_mime: null
                  position: bottom
                  provider: mediaconvert
                  status: queued
                  style: outline
                  text_color: FFFFFF
                  track_uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
                  uid: c3d4e5f6-1b2a-4c3d-9e8f-0a1b2c3d4e5f
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      dub_uid:
                        nullable: true
                      duration_ms:
                        type: integer
                      error_message:
                        nullable: true
                      font_size:
                        type: string
                      has_output:
                        type: boolean
                      language:
                        type: string
                      onto:
                        type: string
                      output_mime:
                        nullable: true
                      position:
                        type: string
                      provider:
                        type: string
                      status:
                        type: string
                      style:
                        type: string
                      text_color:
                        type: string
                      track_uid:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Burn a track''s subtitles into the video. Body: {track_uid, dub_uid?,'
      tags:
      - Video Hub
  /videohub/projects/{project_uid}/dubs:
    get:
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  dubs:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    duration_ms: 754000
                    error_message: null
                    has_output: false
                    language: es
                    output_mime: null
                    provider: elevenlabs
                    source_language: en
                    status: queued
                    uid: b7c1e2f4-0a9d-4e3b-8c5f-1d2a6b7c9e0f
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      dubs:
                        items:
                          properties:
                            created_at:
                              type: string
                            duration_ms:
                              type: integer
                            error_message:
                              nullable: true
                            has_output:
                              type: boolean
                            language:
                              type: string
                            output_mime:
                              nullable: true
                            provider:
                              type: string
                            source_language:
                              type: string
                            status:
                              type: string
                            uid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List a project's AI audio dubs and their status.
      tags:
      - Video Hub
    post:
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              language: es
              source_language: en
            schema:
              properties:
                language:
                  type: string
                source_language:
                  type: string
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  duration_ms: 754000
                  error_message: null
                  has_output: false
                  language: es
                  output_mime: null
                  provider: elevenlabs
                  source_language: en
                  status: queued
                  uid: b7c1e2f4-0a9d-4e3b-8c5f-1d2a6b7c9e0f
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      duration_ms:
                        type: integer
                      error_message:
                        nullable: true
                      has_output:
                        type: boolean
                      language:
                        type: string
                      output_mime:
                        nullable: true
                      provider:
                        type: string
                      source_language:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Start an AI audio dub into a target language. Body: {language, source_language?}.'
      tags:
      - Video Hub
  /videohub/projects/{project_uid}/tracks:
    post:
      parameters:
      - in: path
        name: project_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              label: Spanish
              language: es-ES
              transcribe: true
            schema:
              properties:
                label:
                  type: string
                language:
                  type: string
                transcribe:
                  type: boolean
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  cue_count: 128
                  is_default: true
                  label: English
                  language: en-US
                  source: transcribed
                  status: ready
                  uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
              schema:
                properties:
                  data:
                    properties:
                      cue_count:
                        type: integer
                      is_default:
                        type: boolean
                      label:
                        type: string
                      language:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Create a language track. Body: {language, label?, transcribe?:bool}.'
      tags:
      - Video Hub
  /videohub/tracks/{track_uid}:
    get:
      parameters:
      - in: path
        name: track_uid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  cue_count: 128
                  cues:
                  - end_ms: 2500
                    id: 1
                    source_cue_id: null
                    speaker: null
                    start_ms: 0
                    text: Welcome to the keynote.
                  is_default: true
                  label: English
                  language: en-US
                  source: transcribed
                  status: ready
                  uid: 9a3f2d1c-4b6e-4c8a-8f1d-2e7b5c9a0d3f
              schema:
                properties:
                  data:
                    properties:
                      cue_count:
                        type: integer
                      cues:
                        items:
                          properties:
                            end_ms:
                              type: integer
                            id:
                              type: integer
                            source_cue_id:
                              nullable: true
                            speaker:
                              nullable: true
                            start_ms:
                              type: integer
                            text:
                              type: string
                          type: object
                        type: array
                      is_default:
                        type: boolean
                      label:
                        type: string
                      language:
                        type: string
                      source:
                        type: string
                      status:
                        type: string
                      uid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a track including all its cues.
      tags:
      - Video Hub
  /videohub/tracks/{track_uid}/cues:
    put:
      parameters:
      - in: path
        name: track_uid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              cues:
              - end_ms: 2500
                speaker: null
                start_ms: 0
                text: Welcome to the keynote.
            schema:
              properties:
                cues:
                  items:
                    properties:
                      end_ms:
                        type: integer
                      speaker:
                        nullable: true
                      start_ms:
                        type: integer
                      text:
                        type: string
                    type: object
                  type: array
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  cue_count: 128
              schema:
                properties:
                  data:
                    properties:
                      cue_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Replace all cues on a track. Body: {cues:[{start_ms,end_ms,text,speaker?}]}.'
      tags:
      - Video Hub
  /videohub/tracks/{track_uid}/export:
    get:
      parameters:
      - in: path
        name: track_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  content: 'WEBVTT


                    1

                    00:00:00.000 --> 00:00:02.500

                    Welcome to the keynote.

                    '
                  cue_count: 128
                  format: vtt
              schema:
                properties:
                  data:
                    properties:
                      content:
                        type: string
                      cue_count:
                        type: integer
                      format:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Export a track's subtitles. ?fmt=vtt|srt|txt → {format, content}.
      tags:
      - Video Hub
  /videohub/tracks/{track_uid}/qa:
    get:
      parameters:
      - in: path
        name: track_uid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  cues:
                  - id: 42
                    index: 4
                    issues:
                    - code: cps_max
                      message: Reading speed 24.3 CPS (max 20).
                      severity: error
                  summary:
                    cue_count: 128
                    errors: 1
                    warnings: 3
              schema:
                properties:
                  data:
                    properties:
                      cues:
                        items:
                          properties:
                            id:
                              type: integer
                            index:
                              type: integer
                            issues:
                              items:
                                properties:
                                  code:
                                    type: string
                                  message:
                                    type: string
                                  severity:
                                    type: string
                                type: object
                              type: array
                          type: object
                        type: array
                      summary:
                        properties:
                          cue_count:
                            type: integer
                          errors:
                            type: integer
                          warnings:
                            type: integer
                        type: object
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Run the QA engine on a track against its project's standard.
      tags:
      - Video Hub
  /web-analytics/goals/{goal_id}:
    delete:
      parameters:
      - in: path
        name: goal_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  id: 7
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: integer
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a conversion goal.
      tags:
      - Web Analytics
  /web-analytics/projects:
    get:
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  projects:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    domains:
                    - example.com
                    - www.example.com
                    name: Marketing site
                    retention_days: 90
                    site_key: wa_site_key_example
                    uuid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      projects:
                        items:
                          properties:
                            created_at:
                              type: string
                            domains:
                              items:
                                type: string
                              type: array
                            name:
                              type: string
                            retention_days:
                              type: integer
                            site_key:
                              type: string
                            uuid:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List Web Analytics projects for the tenant.
      tags:
      - Web Analytics
    post:
      requestBody:
        content:
          application/json:
            example:
              domains:
              - example.com
              - www.example.com
              name: Marketing site
            schema:
              properties:
                domains:
                  items:
                    type: string
                  type: array
                name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  domains:
                  - example.com
                  - www.example.com
                  name: Marketing site
                  retention_days: 90
                  site_key: wa_site_key_example
                  uuid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      domains:
                        items:
                          type: string
                        type: array
                      name:
                        type: string
                      retention_days:
                        type: integer
                      site_key:
                        type: string
                      uuid:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Create a Web Analytics project. Body (JSON): { name (req), domains?
        [..] }.'
      tags:
      - Web Analytics
  /web-analytics/projects/{uuid}:
    delete:
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  deleted: true
                  uuid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      deleted:
                        type: boolean
                      uuid:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Delete a project and all its data (events, goals, domains cascade).
      tags:
      - Web Analytics
    patch:
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              domains:
              - example.com
              name: Marketing site
            schema:
              properties:
                domains:
                  items:
                    type: string
                  type: array
                name:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  domains:
                  - example.com
                  - www.example.com
                  name: Marketing site
                  retention_days: 90
                  site_key: wa_site_key_example
                  uuid: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      domains:
                        items:
                          type: string
                        type: array
                      name:
                        type: string
                      retention_days:
                        type: integer
                      site_key:
                        type: string
                      uuid:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Update a project. Body (JSON): { name?, domains? [..] } (domains replaces
        the set).'
      tags:
      - Web Analytics
  /web-analytics/projects/{uuid}/breakdown:
    get:
      description: '&range=7d&limit=10. Pages are grouped by the project''s saved
        URL patterns;

        pass &pages=raw to see ungrouped URLs.'
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  dimension: page
                  project: Marketing site
                  range: Last 7 days
                  rows:
                  - key: /pricing
                    pageviews: 610
                    visitors: 420
              schema:
                properties:
                  data:
                    properties:
                      dimension:
                        type: string
                      project:
                        type: string
                      range:
                        type: string
                      rows:
                        items:
                          properties:
                            key:
                              type: string
                            pageviews:
                              type: integer
                            visitors:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Top-N by a dimension. Query: ?dimension=page|source|country|device|browser|os|utm_campaign'
      tags:
      - Web Analytics
  /web-analytics/projects/{uuid}/goals:
    get:
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  count: 1
                  goals:
                  - created_at: '2026-07-17T12:00:00+00:00'
                    goal_type: pageview
                    id: 7
                    match_value: /welcome
                    name: Signup
              schema:
                properties:
                  data:
                    properties:
                      count:
                        type: integer
                      goals:
                        items:
                          properties:
                            created_at:
                              type: string
                            goal_type:
                              type: string
                            id:
                              type: integer
                            match_value:
                              type: string
                            name:
                              type: string
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List conversion goals for a project.
      tags:
      - Web Analytics
    post:
      description: (pageview|event), match_value (req — a path/path* or event name)
        }.
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              goal_type: pageview
              match_value: /welcome
              name: Signup
            schema:
              properties:
                goal_type:
                  type: string
                match_value:
                  type: string
                name:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  created_at: '2026-07-17T12:00:00+00:00'
                  goal_type: pageview
                  id: 7
                  match_value: /welcome
                  name: Signup
              schema:
                properties:
                  data:
                    properties:
                      created_at:
                        type: string
                      goal_type:
                        type: string
                      id:
                        type: integer
                      match_value:
                        type: string
                      name:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Create a conversion goal. Body (JSON): { name (req), goal_type'
      tags:
      - Web Analytics
  /web-analytics/projects/{uuid}/stats:
    get:
      parameters:
      - in: path
        name: uuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  project: Marketing site
                  range: Last 7 days
                  realtime_visitors: 12
                  summary:
                    bounce_rate: 38
                    pageviews: 3980
                    views_per_visit: 2.5
                    visitors: 1240
                    visits: 1610
                  timeseries:
                  - bucket: '2026-07-16T00:00:00+00:00'
                    pageviews: 512
                    visitors: 190
              schema:
                properties:
                  data:
                    properties:
                      project:
                        type: string
                      range:
                        type: string
                      realtime_visitors:
                        type: integer
                      summary:
                        properties:
                          bounce_rate:
                            type: integer
                          pageviews:
                            type: integer
                          views_per_visit:
                            type: number
                          visitors:
                            type: integer
                          visits:
                            type: integer
                        type: object
                      timeseries:
                        items:
                          properties:
                            bucket:
                              type: string
                            pageviews:
                              type: integer
                            visitors:
                              type: integer
                          type: object
                        type: array
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: 'Summary + realtime for a project. Query: ?range=today|7d|30d|12mo
        (default 7d).'
      tags:
      - Web Analytics
  /websites:
    get:
      description: List all websites for the tenant workspace.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/WebsiteSite'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List websites
      tags:
      - Websites
  /websites/{site_id}:
    get:
      description: Get a single website by ID.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebsiteSite'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get website
      tags:
      - Websites
    patch:
      description: Update website name or published state.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                is_published:
                  type: boolean
                name:
                  type: string
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebsiteSite'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update website
      tags:
      - Websites
  /websites/{site_id}/pages:
    get:
      description: List all pages for a website.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/WebsitePage'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List pages
      tags:
      - Websites
  /websites/{site_id}/pages/{page_id}:
    get:
      description: Get a single page by ID.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      - in: path
        name: page_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebsitePage'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get page
      tags:
      - Websites
    patch:
      description: Update page title, slug, or published state.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      - in: path
        name: page_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                is_published:
                  type: boolean
                slug:
                  type: string
                title:
                  type: string
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebsitePage'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update page
      tags:
      - Websites
  /websites/{site_id}/pages/{page_id}/versions:
    get:
      description: List version history for a page.
      parameters:
      - in: path
        name: site_id
        required: true
        schema:
          type: integer
      - in: path
        name: page_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/WebsitePage'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List page versions
      tags:
      - Websites
  /wiki/pages/{page_id}:
    delete:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  archived: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
              schema:
                properties:
                  data:
                    properties:
                      archived:
                        type: string
                    type: object
                type: object
          description: Deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Archive (soft-delete) a page.
      tags:
      - Wiki
    get:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  content: '{"type":"doc","content":[]}'
                  created_at: '2026-01-17T11:00:00+00:00'
                  icon: 📄
                  id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  is_stale: false
                  is_verified: true
                  parent_id: null
                  space_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  status: published
                  title: Getting Started
                  updated_at: '2026-02-01T14:20:00+00:00'
                  view_count: 87
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  word_count: 640
              schema:
                properties:
                  data:
                    properties:
                      author_id:
                        type: string
                      author_name:
                        type: string
                      content:
                        type: string
                      created_at:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_stale:
                        type: boolean
                      is_verified:
                        type: boolean
                      parent_id:
                        nullable: true
                      space_id:
                        type: string
                      status:
                        type: string
                      title:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                      wiki_id:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a page by UUID (includes full TipTap content).
      tags:
      - Wiki
    patch:
      description: "Body (JSON):\n  title    (str)\n  content  (str, TipTap JSON)\n\
        \  icon     (str, emoji)"
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content: '{"type":"doc","content":[]}'
              icon: 📄
              title: Getting Started
            schema:
              properties:
                content:
                  type: string
                icon:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  content: '{"type":"doc","content":[]}'
                  created_at: '2026-01-17T11:00:00+00:00'
                  icon: 📄
                  id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  is_stale: false
                  is_verified: true
                  parent_id: null
                  space_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  status: published
                  title: Getting Started
                  updated_at: '2026-02-01T14:20:00+00:00'
                  view_count: 87
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  word_count: 640
              schema:
                properties:
                  data:
                    properties:
                      author_id:
                        type: string
                      author_name:
                        type: string
                      content:
                        type: string
                      created_at:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_stale:
                        type: boolean
                      is_verified:
                        type: boolean
                      parent_id:
                        nullable: true
                      space_id:
                        type: string
                      status:
                        type: string
                      title:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                      wiki_id:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a page's title, content, or icon.
      tags:
      - Wiki
  /wiki/pages/{page_id}/comments:
    get:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  body: Looks good to me.
                  created_at: '2026-02-02T09:15:00+00:00'
                  id: c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f
                  is_resolved: false
                  page_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  parent_id: null
              schema:
                properties:
                  data:
                    items:
                      properties:
                        author_id:
                          type: string
                        author_name:
                          type: string
                        body:
                          type: string
                        created_at:
                          type: string
                        id:
                          type: string
                        is_resolved:
                          type: boolean
                        page_id:
                          type: string
                        parent_id:
                          nullable: true
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List top-level comments on a page.
      tags:
      - Wiki
    post:
      description: "Body (JSON):\n  body       (str, required, max 2000 chars)\n \
        \ parent_id  (str, UUID of parent comment for threading — optional)"
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              body: Looks good to me.
              parent_id: null
            schema:
              properties:
                body:
                  type: string
                parent_id:
                  nullable: true
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  body: Looks good to me.
                  created_at: '2026-02-02T09:15:00+00:00'
                  id: c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f
                  is_resolved: false
                  page_id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  parent_id: null
              schema:
                properties:
                  data:
                    properties:
                      author_id:
                        type: string
                      author_name:
                        type: string
                      body:
                        type: string
                      created_at:
                        type: string
                      id:
                        type: string
                      is_resolved:
                        type: boolean
                      page_id:
                        type: string
                      parent_id:
                        nullable: true
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Post a comment on a page.
      tags:
      - Wiki
  /wiki/pages/{page_id}/versions:
    get:
      parameters:
      - in: path
        name: page_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_at: '2026-02-01T14:20:00+00:00'
                  edit_summary: Updated setup steps
                  editor_name: Jane Doe
                  version_number: 3
                  word_count: 640
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          type: string
                        edit_summary:
                          type: string
                        editor_name:
                          type: string
                        version_number:
                          type: integer
                        word_count:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List version history for a page.
      tags:
      - Wiki
  /wiki/spaces/{space_id}:
    get:
      parameters:
      - in: path
        name: space_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  color: '#6366f1'
                  created_at: '2026-01-16T10:00:00+00:00'
                  description: New-hire onboarding docs
                  icon: 📁
                  id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  is_public: true
                  page_count: 12
                  title: Onboarding
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_public:
                        type: boolean
                      page_count:
                        type: integer
                      title:
                        type: string
                      wiki_id:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a space by UUID.
      tags:
      - Wiki
  /wiki/spaces/{space_id}/pages:
    get:
      parameters:
      - in: path
        name: space_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  created_at: '2026-01-17T11:00:00+00:00'
                  icon: 📄
                  id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  is_stale: false
                  is_verified: true
                  parent_id: null
                  space_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  status: published
                  title: Getting Started
                  updated_at: '2026-02-01T14:20:00+00:00'
                  view_count: 87
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  word_count: 640
              schema:
                properties:
                  data:
                    items:
                      properties:
                        author_id:
                          type: string
                        author_name:
                          type: string
                        created_at:
                          type: string
                        icon:
                          type: string
                        id:
                          type: string
                        is_stale:
                          type: boolean
                        is_verified:
                          type: boolean
                        parent_id:
                          nullable: true
                        space_id:
                          type: string
                        status:
                          type: string
                        title:
                          type: string
                        updated_at:
                          type: string
                        view_count:
                          type: integer
                        wiki_id:
                          type: string
                        word_count:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all pages in a space (no content — use GET /wiki/pages/<id> for
        full content).
      tags:
      - Wiki
    post:
      description: "Body (JSON):\n  title        (str, required)\n  content      (str,\
        \ TipTap JSON — optional)\n  icon         (str, emoji — optional)\n  parent_id\
        \    (str, UUID of parent page — optional)"
      parameters:
      - in: path
        name: space_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              content: '{"type":"doc","content":[]}'
              icon: 📄
              parent_id: null
              title: Getting Started
            schema:
              properties:
                content:
                  type: string
                icon:
                  type: string
                parent_id:
                  nullable: true
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  content: '{"type":"doc","content":[]}'
                  created_at: '2026-01-17T11:00:00+00:00'
                  icon: 📄
                  id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  is_stale: false
                  is_verified: true
                  parent_id: null
                  space_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  status: published
                  title: Getting Started
                  updated_at: '2026-02-01T14:20:00+00:00'
                  view_count: 87
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  word_count: 640
              schema:
                properties:
                  data:
                    properties:
                      author_id:
                        type: string
                      author_name:
                        type: string
                      content:
                        type: string
                      created_at:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_stale:
                        type: boolean
                      is_verified:
                        type: boolean
                      parent_id:
                        nullable: true
                      space_id:
                        type: string
                      status:
                        type: string
                      title:
                        type: string
                      updated_at:
                        type: string
                      view_count:
                        type: integer
                      wiki_id:
                        type: string
                      word_count:
                        type: integer
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new page in a space.
      tags:
      - Wiki
  /wiki/templates/{template_id}:
    get:
      parameters:
      - in: path
        name: template_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  content: '{"type":"doc","content":[]}'
                  icon: 📝
                  id: d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80
                  title: Meeting Notes
              schema:
                properties:
                  data:
                    properties:
                      content:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a wiki page template by UUID (used by the editor Insert template
        dropdown).
      tags:
      - Wiki
  /wiki/wikis:
    get:
      description: Returns all wikis accessible to the authenticated tenant.
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Wiki'
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List wikis
      tags:
      - Wiki
    post:
      requestBody:
        content:
          application/json:
            example:
              ai_enabled: true
              description: Internal engineering docs
              icon: 📖
              title: Engineering Handbook
            schema:
              properties:
                ai_enabled:
                  type: boolean
                description:
                  type: string
                icon:
                  type: string
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  ai_enabled: true
                  created_at: '2026-01-15T09:30:00+00:00'
                  description: Internal engineering docs
                  icon: 📖
                  id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  is_enabled: true
                  space_count: 4
                  title: Engineering Handbook
              schema:
                properties:
                  data:
                    properties:
                      ai_enabled:
                        type: boolean
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      space_count:
                        type: integer
                      title:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new wiki.
      tags:
      - Wiki
  /wiki/wikis/{wiki_id}:
    get:
      parameters:
      - in: path
        name: wiki_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_enabled: true
                  created_at: '2026-01-15T09:30:00+00:00'
                  description: Internal engineering docs
                  icon: 📖
                  id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  is_enabled: true
                  space_count: 4
                  title: Engineering Handbook
              schema:
                properties:
                  data:
                    properties:
                      ai_enabled:
                        type: boolean
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      space_count:
                        type: integer
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Get a wiki by UUID.
      tags:
      - Wiki
    patch:
      parameters:
      - in: path
        name: wiki_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              ai_enabled: false
              description: Internal engineering docs
              icon: 📖
              is_enabled: true
              title: Engineering Handbook
            schema:
              properties:
                ai_enabled:
                  type: boolean
                description:
                  type: string
                icon:
                  type: string
                is_enabled:
                  type: boolean
                title:
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  ai_enabled: true
                  created_at: '2026-01-15T09:30:00+00:00'
                  description: Internal engineering docs
                  icon: 📖
                  id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  is_enabled: true
                  space_count: 4
                  title: Engineering Handbook
              schema:
                properties:
                  data:
                    properties:
                      ai_enabled:
                        type: boolean
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      space_count:
                        type: integer
                      title:
                        type: string
                    type: object
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Update a wiki's settings.
      tags:
      - Wiki
  /wiki/wikis/{wiki_id}/search:
    get:
      description: "Query params:\n  q   (str, required)"
      parameters:
      - in: path
        name: wiki_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - author_id: u_9f8e7d6c5b4a
                  author_name: Jane Doe
                  created_at: '2026-01-17T11:00:00+00:00'
                  icon: 📄
                  id: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
                  is_stale: false
                  is_verified: true
                  parent_id: null
                  space_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  status: published
                  title: Getting Started
                  updated_at: '2026-02-01T14:20:00+00:00'
                  view_count: 87
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
                  word_count: 640
              schema:
                properties:
                  data:
                    items:
                      properties:
                        author_id:
                          type: string
                        author_name:
                          type: string
                        created_at:
                          type: string
                        icon:
                          type: string
                        id:
                          type: string
                        is_stale:
                          type: boolean
                        is_verified:
                          type: boolean
                        parent_id:
                          nullable: true
                        space_id:
                          type: string
                        status:
                          type: string
                        title:
                          type: string
                        updated_at:
                          type: string
                        view_count:
                          type: integer
                        wiki_id:
                          type: string
                        word_count:
                          type: integer
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Full-text search across pages in a wiki.
      tags:
      - Wiki
  /wiki/wikis/{wiki_id}/spaces:
    get:
      parameters:
      - in: path
        name: wiki_id
        required: true
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: per_page
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - color: '#6366f1'
                  created_at: '2026-01-16T10:00:00+00:00'
                  description: New-hire onboarding docs
                  icon: 📁
                  id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  is_public: true
                  page_count: 12
                  title: Onboarding
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
              schema:
                properties:
                  data:
                    items:
                      properties:
                        color:
                          type: string
                        created_at:
                          type: string
                        description:
                          type: string
                        icon:
                          type: string
                        id:
                          type: string
                        is_public:
                          type: boolean
                        page_count:
                          type: integer
                        title:
                          type: string
                        wiki_id:
                          type: string
                      type: object
                    type: array
                type: object
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: List all spaces in a wiki.
      tags:
      - Wiki
    post:
      parameters:
      - in: path
        name: wiki_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              color: '#6366f1'
              description: New-hire onboarding docs
              icon: 📁
              is_public: true
              title: Onboarding
            schema:
              properties:
                color:
                  type: string
                description:
                  type: string
                icon:
                  type: string
                is_public:
                  type: boolean
                title:
                  type: string
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  color: '#6366f1'
                  created_at: '2026-01-16T10:00:00+00:00'
                  description: New-hire onboarding docs
                  icon: 📁
                  id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  is_public: true
                  page_count: 12
                  title: Onboarding
                  wiki_id: 3f9a1c2e-7b4d-4e2a-9c1f-8a2b3c4d5e6f
              schema:
                properties:
                  data:
                    properties:
                      color:
                        type: string
                      created_at:
                        type: string
                      description:
                        type: string
                      icon:
                        type: string
                      id:
                        type: string
                      is_public:
                        type: boolean
                      page_count:
                        type: integer
                      title:
                        type: string
                      wiki_id:
                        type: string
                    type: object
                type: object
          description: Created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
      security:
      - ApiSecretHeader: []
        ApiTokenHeader: []
      summary: Create a new space in a wiki.
      tags:
      - Wiki
security:
- ApiSecretHeader: []
  ApiTokenHeader: []
servers:
- description: Current server
  url: https://api.totalctrl.app/api/v1
tags:
- name: AI Agent & Knowledge
- description: Prompt templates, versions, and evaluation runs.
  name: AI Prompts
- name: Academy
- name: Account
- name: Accounting
- name: Analytics
- name: Assets
- name: Automations
- name: Block Templates
- description: Contacts, companies, deals, pipelines, and activities.
  name: CRM
- name: Calendar
- name: Community
- description: Reusable snippets, topics, and variables.
  name: Content Components (CCMS)
- name: Creator
- description: Accounts, health, tasks, and playbooks.
  name: Customer Success (CSM)
- description: E-signature envelopes and recipients.
  name: Document Signing
- name: Employee Directory
- name: Engage
- name: File Transfer & Requests
- name: Help Center
- description: Projects, issues, epics, sprints, labels, and comments.
  name: Issue Tracking
- name: Landing Pages
- name: Newsletter
- name: Notes
- name: Orchestration
- name: Org Charts
- name: Platform Messaging
- description: Products, feeds, and channel connectors.
  name: Product Information (PIM)
- name: Product Requests
- description: Projects, columns, tasks, subtasks, and labels.
  name: Project Manager
- name: Project Tasks
- name: Session Replay
- name: Signals
- description: Glossaries, style rules, and checks.
  name: Standards & Compliance
- name: String Manager
- name: Support
- name: Surveys
- description: Time entries, timers, and projects.
  name: Time Tracking
- name: Unified Contacts
- name: Video Hub
- name: Web Analytics
- name: Websites
- name: Wiki
