openapi: 3.0.3
info:
  title: Numbors API
  version: 1.0.0
  description: |
    The Numbors REST API lets you programmatically manage contacts, invoices,
    transactions, inventory, payroll, CRM, and every other module available
    in the Numbors platform.

    All endpoints (except authentication and public support chat) require
    a valid JWT Bearer token **and** a company context supplied via the
    `X-Company-Id` header.

    **Additional API suites:**
    - Support Chat (`/api/support/*`) -- public AI-powered support
    - AI Insights (`/api/ai-insights/*`) -- AI-powered report analysis
    - Tai Dev Lifecycle (`/api/tai/*`) -- internal dev tooling
    - Compliance (`/api/compliance/*`) -- compliance posture & audit export
  contact:
    name: Numbors Support
    url: https://app.numbors.com/hub
  license:
    name: Proprietary

servers:
  - url: https://app.numbors.com/api
    description: Production
  - url: http://localhost:3003/api
    description: Local development

security:
  - BearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Obtain a token via `POST /api/auth/login`, then send it as
        `Authorization: Bearer <token>` on every subsequent request.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Long-lived API key created in Settings > API Keys.
        Send as `X-API-Key: nb_your_key_here`. No X-Company-Id header needed --
        the key is scoped to the company it was created for.

  headers:
    X-Company-Id:
      description: The MongoDB ObjectId of the company to operate on. Required for all endpoints after authentication.
      schema:
        type: string
        example: 507f1f77bcf86cd799439011

  parameters:
    idParam:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: MongoDB ObjectId
    pageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description: Page number
    limitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 25
      description: Items per page

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: Invalid credentials
    Success:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
    PaginatedMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer

tags:
  - name: Authentication
    description: "Register, login, and retrieve the current user."
  - name: Modules
    description: Query enabled modules and license information.
  - name: Companies
    description: List companies accessible to the authenticated user.
  - name: Contacts
    description: "Manage customers, suppliers, and other contacts."
  - name: Documents
    description: "Create and manage invoices, bills, and other financial documents."
  - name: Accounts
    description: Bank accounts and cash accounts.
  - name: Transactions
    description: Income and expense transactions.
  - name: Items
    description: Products and services used on invoices and bills.
  - name: Categories
    description: Income and expense categories.
  - name: Taxes
    description: Tax rates applied to line items.
  - name: Currencies
    description: Multi-currency support.
  - name: Estimates
    description: Quotes and estimates sent to customers.
  - name: Credit Notes
    description: Credit notes issued against invoices.
  - name: Accounting
    description: Chart of accounts and journal entries.
  - name: Inventory
    description: "Warehouses, stock transfers, and adjustments."
  - name: Projects
    description: Project management and time tracking.
  - name: Payroll
    description: "Departments, employees, and pay runs."
  - name: Point of Sale
    description: "POS terminals, sessions, orders, and loyalty programmes."
  - name: CRM
    description: "Pipelines, leads, deals, activities, and campaigns."
  - name: "Contracts & Proposals"
    description: Manage contracts and send proposals.
  - name: Helpdesk
    description: "Ticket categories, tickets, SLAs, and knowledge-base articles."
  - name: Orders
    description: Sales orders and purchase orders.
  - name: Banking
    description: "Open-banking feeds, connections, and auto-categorisation rules."
  - name: Transfers
    description: Inter-account transfers.
  - name: Support Chat
    description: Public AI-powered support chat. No authentication required for chat and history.
  - name: Tai Dev Lifecycle
    description: "Internal dev lifecycle management: bugs, roadmap, features, and AI experts."
  - name: Tai Features
    description: Feature tracking via Buggazi integration.
  - name: Tai Sprints
    description: Sprint management via Buggazi integration.
  - name: Tai Bugfixer
    description: Automated bug-fixing conductor and stats.
  - name: Tai Seed Conductor
    description: Seed data profile management and recommendation.
  - name: AI Insights
    description: AI-powered financial report analysis and insights.
  - name: Compliance
    description: Compliance posture snapshots and OCSF audit export.

paths:
  # -- Authentication ──────────────────────────────────────────────
  /auth/register:
    post:
      tags: [Authentication]
      summary: Register a new user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/login:
    post:
      tags: [Authentication]
      summary: Log in and receive a JWT
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/me:
    get:
      tags: [Authentication]
      summary: Get current authenticated user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Modules ─────────────────────────────────────────────────────
  /modules/enabled:
    get:
      tags: [Modules]
      summary: List enabled modules
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /modules/check/{alias}:
    get:
      tags: [Modules]
      summary: Check if specific module is accessible
      parameters:
        - name: alias
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/licenses:
    get:
      tags: [Modules]
      summary: Get detailed license information
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Companies ───────────────────────────────────────────────────
  /companies:
    get:
      tags: [Companies]
      summary: List accessible companies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Contacts ────────────────────────────────────────────────────
  /contacts:
    get:
      tags: [Contacts]
      summary: List contacts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Contacts]
      summary: Create a contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contacts/{id}:
    get:
      tags: [Contacts]
      summary: Get a contacts
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags: [Contacts]
      summary: Update a contacts
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
    delete:
      tags: [Contacts]
      summary: Delete a contacts
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  # -- Documents ───────────────────────────────────────────────────
  /documents:
    get:
      tags: [Documents]
      summary: List documents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Documents]
      summary: Create a documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /documents/{id}:
    get:
      tags: [Documents]
      summary: Get a documents
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags: [Documents]
      summary: Update a documents
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
    delete:
      tags: [Documents]
      summary: Delete a documents
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  # -- Accounts ────────────────────────────────────────────────────
  /accounts:
    get:
      tags: [Accounts]
      summary: List accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Accounts]
      summary: Create an accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Transactions ────────────────────────────────────────────────
  /transactions:
    get:
      tags: [Transactions]
      summary: List transactions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Transactions]
      summary: Create a transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Items ───────────────────────────────────────────────────────
  /items:
    get:
      tags: [Items]
      summary: List items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Items]
      summary: Create an items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Categories ──────────────────────────────────────────────────
  /categories:
    get:
      tags: [Categories]
      summary: List categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Categories]
      summary: Create a categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Taxes ───────────────────────────────────────────────────────
  /taxes:
    get:
      tags: [Taxes]
      summary: List taxes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Taxes]
      summary: Create a taxes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Currencies ──────────────────────────────────────────────────
  /currencies:
    get:
      tags: [Currencies]
      summary: List currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Currencies]
      summary: Create a currencies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Taxes ───────────────────────────────────────────────────────
  /taxes/{id}:
    put:
      tags: [Taxes]
      summary: Update a taxes
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
  # -- Categories ──────────────────────────────────────────────────
  /categories/{id}:
    put:
      tags: [Categories]
      summary: Update a categories
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
  # -- Estimates ───────────────────────────────────────────────────
  /estimates:
    get:
      tags: [Estimates]
      summary: List estimates
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Estimates]
      summary: Create an estimates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /estimates/{id}:
    get:
      tags: [Estimates]
      summary: Get an estimates
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags: [Estimates]
      summary: Update an estimates
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
    delete:
      tags: [Estimates]
      summary: Delete an estimates
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  # -- Credit Notes ────────────────────────────────────────────────
  /credit-notes:
    get:
      tags: [Credit Notes]
      summary: List credit notes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Credit Notes]
      summary: Create a credit notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Accounting ──────────────────────────────────────────────────
  /accounting/chart-of-accounts:
    get:
      tags: [Accounting]
      summary: List accounting chart of accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Accounting]
      summary: Create an accounting chart of accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounting/journal:
    get:
      tags: [Accounting]
      summary: List accounting journal
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Accounting]
      summary: Create an accounting journal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Inventory ───────────────────────────────────────────────────
  /inventory/warehouses:
    get:
      tags: [Inventory]
      summary: List inventory warehouses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Inventory]
      summary: Create an inventory warehouses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /inventory/transfers:
    get:
      tags: [Inventory]
      summary: List inventory transfers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Inventory]
      summary: Create an inventory transfers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /inventory/adjustments:
    post:
      tags: [Inventory]
      summary: Create an inventory adjustments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Projects ────────────────────────────────────────────────────
  /projects:
    get:
      tags: [Projects]
      summary: List projects
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Projects]
      summary: Create a projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /projects/{id}:
    get:
      tags: [Projects]
      summary: Get a projects
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags: [Projects]
      summary: Update a projects
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
  /projects/{id}/tasks:
    post:
      tags: [Projects]
      summary: Create a projects tasks
      parameters:
        - $ref: '#/components/parameters/idParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /projects/time:
    get:
      tags: [Projects]
      summary: List projects time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Projects]
      summary: Create a projects time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Payroll ─────────────────────────────────────────────────────
  /payroll/departments:
    get:
      tags: [Payroll]
      summary: List payroll departments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Payroll]
      summary: Create a payroll departments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /payroll/employees:
    get:
      tags: [Payroll]
      summary: List payroll employees
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Payroll]
      summary: Create a payroll employees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /payroll/pay-runs:
    get:
      tags: [Payroll]
      summary: List payroll pay runs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Payroll]
      summary: Create a payroll pay runs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Point of Sale ───────────────────────────────────────────────
  /pos/terminals:
    get:
      tags: [Point of Sale]
      summary: List pos terminals
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Point of Sale]
      summary: Create a pos terminals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pos/sessions:
    get:
      tags: [Point of Sale]
      summary: List pos sessions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /pos/sessions/open:
    post:
      tags: [Point of Sale]
      summary: Open a new POS session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pos/orders:
    post:
      tags: [Point of Sale]
      summary: Create a pos orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pos/loyalty:
    get:
      tags: [Point of Sale]
      summary: List pos loyalty
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /pos/loyalty/programs:
    post:
      tags: [Point of Sale]
      summary: Create a pos loyalty programs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- CRM ─────────────────────────────────────────────────────────
  /crm/pipelines:
    get:
      tags: [CRM]
      summary: List crm pipelines
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [CRM]
      summary: Create a crm pipelines
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/leads:
    get:
      tags: [CRM]
      summary: List crm leads
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [CRM]
      summary: Create a crm leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/deals:
    get:
      tags: [CRM]
      summary: List crm deals
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [CRM]
      summary: Create a crm deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/activities:
    get:
      tags: [CRM]
      summary: List crm activities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [CRM]
      summary: Create a crm activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/campaigns:
    get:
      tags: [CRM]
      summary: List crm campaigns
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [CRM]
      summary: Create a crm campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Contracts & Proposals ───────────────────────────────────────
  /contracts:
    get:
      tags: ["Contracts & Proposals"]
      summary: List contracts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: ["Contracts & Proposals"]
      summary: Create a contracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contracts/proposals:
    get:
      tags: ["Contracts & Proposals"]
      summary: List contracts proposals
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: ["Contracts & Proposals"]
      summary: Create a contracts proposals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Helpdesk ────────────────────────────────────────────────────
  /helpdesk/categories:
    get:
      tags: [Helpdesk]
      summary: List helpdesk categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Helpdesk]
      summary: Create a helpdesk categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /helpdesk/tickets:
    get:
      tags: [Helpdesk]
      summary: List helpdesk tickets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Helpdesk]
      summary: Create a helpdesk tickets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /helpdesk/slas:
    get:
      tags: [Helpdesk]
      summary: List helpdesk slas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Helpdesk]
      summary: Create a helpdesk slas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /helpdesk/articles:
    get:
      tags: [Helpdesk]
      summary: List helpdesk articles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Helpdesk]
      summary: Create a helpdesk articles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Orders ──────────────────────────────────────────────────────
  /sales/orders:
    get:
      tags: [Orders]
      summary: List sales orders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Orders]
      summary: Create a sales orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /purchases/orders:
    get:
      tags: [Orders]
      summary: List purchases orders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Orders]
      summary: Create a purchases orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Banking ─────────────────────────────────────────────────────
  /banking/feeds:
    get:
      tags: [Banking]
      summary: List banking feeds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /banking/feeds/connections:
    get:
      tags: [Banking]
      summary: List banking feeds connections
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Banking]
      summary: Create a banking feeds connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /banking/feeds/rules:
    get:
      tags: [Banking]
      summary: List banking feeds rules
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Banking]
      summary: Create a banking feeds rules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Transfers ───────────────────────────────────────────────────
  /transfers:
    get:
      tags: [Transfers]
      summary: List transfers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
    post:
      tags: [Transfers]
      summary: Create a transfers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Support Chat ────────────────────────────────────────────────
  /support/chat:
    post:
      tags: [Support Chat]
      summary: Send message and get AI response
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /support/history/{sessionId}:
    get:
      tags: [Support Chat]
      summary: "─── GET /api/support/history/:sessionId — PUBLIC ───────────────────────────"
      security: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /support/escalate:
    post:
      tags: [Support Chat]
      summary: Escalate to helpdesk ticket (auth required)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Tai Dev Lifecycle ───────────────────────────────────────────
  /tai/message:
    post:
      tags: [Tai Dev Lifecycle]
      summary: Ask Tai a question
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/status:
    get:
      tags: [Tai Dev Lifecycle]
      summary: Get system state summary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/bugs:
    get:
      tags: [Tai Dev Lifecycle]
      summary: List tracked bugs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/bug:
    post:
      tags: [Tai Dev Lifecycle]
      summary: Report a bug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/roadmap:
    get:
      tags: [Tai Dev Lifecycle]
      summary: Get current roadmap
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Tai Features ────────────────────────────────────────────────
  /tai/feature:
    post:
      tags: [Tai Features]
      summary: Add a feature
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Tai Dev Lifecycle ───────────────────────────────────────────
  /tai/e2e-fix:
    post:
      tags: [Tai Dev Lifecycle]
      summary: Auto-create bug from E2E failure
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/log:
    get:
      tags: [Tai Dev Lifecycle]
      summary: Get recent session log
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/experts:
    get:
      tags: [Tai Dev Lifecycle]
      summary: List registered experts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Tai Sprints ─────────────────────────────────────────────────
  /tai/sprint/active:
    get:
      tags: [Tai Sprints]
      summary: Get active sprint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/sprint:
    post:
      tags: [Tai Sprints]
      summary: Create a sprint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/sprint/{sprintId}:
    patch:
      tags: [Tai Sprints]
      summary: Update a tai sprint
      parameters:
        - name: sprintId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
  # -- Tai Features ────────────────────────────────────────────────
  /tai/features:
    get:
      tags: [Tai Features]
      summary: List features
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/features/board:
    get:
      tags: [Tai Features]
      summary: Get feature board
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/features/stats:
    get:
      tags: [Tai Features]
      summary: Get feature stats
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/feature/{featureId}:
    patch:
      tags: [Tai Features]
      summary: Update a tai feature
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
  /tai/feature/{featureId}/link-bug:
    post:
      tags: [Tai Features]
      summary: Create a tai feature link bug
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  # -- Tai Bugfixer ────────────────────────────────────────────────
  /tai/bugfix/{domain}:
    post:
      tags: [Tai Bugfixer]
      summary: Create a tai bugfix
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/bugfix/stats:
    get:
      tags: [Tai Bugfixer]
      summary: Get bug-fix stats
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Tai Seed Conductor ──────────────────────────────────────────
  /tai/seed/profiles:
    get:
      tags: [Tai Seed Conductor]
      summary: List seed profiles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/seed/profile/{id}:
    get:
      tags: [Tai Seed Conductor]
      summary: "─── GET /api/tai/seed/profile/:id ──────────────────────────────────────────"
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/seed/recommend:
    post:
      tags: [Tai Seed Conductor]
      summary: Recommend a seed profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tai/seed/state:
    get:
      tags: [Tai Seed Conductor]
      summary: Get seed state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /tai/seed/graph:
    get:
      tags: [Tai Seed Conductor]
      summary: Get seeder dependency graph
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- AI Insights ─────────────────────────────────────────────────
  /ai-insights/status:
    get:
      tags: [AI Insights]
      summary: Check AI availability
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /ai-insights/workflows:
    get:
      tags: [AI Insights]
      summary: List available conductor workflows
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /ai-insights/analyse:
    post:
      tags: [AI Insights]
      summary: Generate AI insights for a report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ai-insights/analyse-stream:
    post:
      tags: [AI Insights]
      summary: Stream AI analysis via SSE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ai-insights/audit:
    get:
      tags: [AI Insights]
      summary: Get AI insight audit trail
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /ai-insights/memory-hook:
    post:
      tags: [AI Insights]
      summary: AgenticMemory webhook for real-time notifications
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ai-insights/shared:
    post:
      tags: [AI Insights]
      summary: Write shared world memory fact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags: [AI Insights]
      summary: Read shared world memory facts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  # -- Compliance ──────────────────────────────────────────────────
  /compliance/snapshot:
    get:
      tags: [Compliance]
      summary: Get full compliance posture snapshot
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
  /compliance/export:
    get:
      tags: [Compliance]
      summary: Export OCSF audit data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object