openapi: "3.1.0"
info:
  title: Kohnex Brain API
  description: Decision Intelligence for AI Agents and LLMs. Cross-domain knowledge graph with nature-inspired metaphors, ancient wisdom, and eureka connections.
  version: "1.0.0"
servers:
  - url: https://kohnex.com
    description: Kohnex Brain production server

paths:
  /api/v1/think:
    post:
      summary: Run brain activation on a query or get a structured methodology
      description: For 'how to' queries (methodology, framework, step by step, design pattern), returns a structured methodology with ordered steps and knowledge graph references. For exploration queries, returns top nodes, nature metaphor, ancient wisdom, eureka connections, and core answer.
      operationId: kohnex_think
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: Your question or topic for the brain
                  maxLength: 4000
                mode:
                  type: string
                  description: Thinking mode (focus, explore, out-of-box, dream, intuitive, beamform, swarm, predator, regeneration, hibernate, immune, photosynthesis, quantum, or auto)
                  default: auto
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful activation or methodology
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  type:
                    type: string
                    enum: [exploration, methodology]
                  confidence:
                    type: number
                  modes_used:
                    type: array
                    items: {type: string}
                  top_nodes:
                    type: array
                    items:
                      type: object
                      properties:
                        id: {type: string}
                        label: {type: string}
                        type: {type: string}
                        activation: {type: number}
                  nature_metaphor:
                    type: object
                    nullable: true
                  ancient_wisdom:
                    type: object
                    nullable: true
                  eureka:
                    type: array
                  core_answer:
                    type: string
                  methodology:
                    type: object
                    nullable: true
  /api/v1/path:
    post:
      summary: Find shortest path between concepts
      operationId: kohnex_path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source_id, target_id]
              properties:
                source_id: {type: string, description: Source node ID}
                target_id: {type: string, description: Target node ID}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Path found
  /api/v1/domain:
    post:
      summary: List nodes in a domain
      operationId: kohnex_domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain_name]
              properties:
                domain_name: {type: string, description: 'Domain name: e.g. performance, cyber, fault, sovereign_math'}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Domain nodes listed
  /api/v1/mode:
    post:
      summary: Describe a thinking mode
      operationId: kohnex_mode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mode_name]
              properties:
                mode_name: {type: string, description: 'Mode name: focus, explore, out-of-box, dream, intuitive, beamform, swarm, predator, regeneration, hibernate, immune, photosynthesis, quantum'}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Mode description
  /api/v1/stats:
    get:
      summary: Brain statistics
      operationId: kohnex_stats
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Brain node/edge/domain counts
  /api/v1/methodologies:
    get:
      summary: List all methodologies
      operationId: kohnex_methodologies
      parameters:
        - name: tag
          in: query
          schema: {type: string}
          description: Filter by tag
        - name: domain
          in: query
          schema: {type: string}
          description: Filter by domain
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of methodologies
  /api/v1/methodologies/generate:
    post:
      summary: AI-generate a methodology from a prompt
      operationId: kohnex_methodology_generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt: {type: string}
                domain: {type: string}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Generated methodology
  /api/v1/methodologies/create:
    post:
      summary: Create a user-defined methodology
      operationId: kohnex_methodology_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, steps]
              properties:
                name: {type: string}
                description: {type: string}
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      order: {type: integer}
                      name: {type: string}
                      description: {type: string}
                      knowledge_nodes: {type: array, items: {type: string}}
                      nature_pattern: {type: string}
                      principle: {type: string}
                tags: {type: array, items: {type: string}}
                domains: {type: array, items: {type: string}}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Created methodology
  /api/v1/methodologies/{id}:
    get:
      summary: Get a methodology by ID
      operationId: kohnex_methodology_get
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Full methodology with steps
    put:
      summary: Update an existing methodology
      operationId: kohnex_methodology_update
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: {type: string}
                description: {type: string}
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      order: {type: integer}
                      name: {type: string}
                      description: {type: string}
                      knowledge_nodes: {type: array, items: {type: string}}
                      nature_pattern: {type: string}
                      principle: {type: string}
                tags: {type: array, items: {type: string}}
                domains: {type: array, items: {type: string}}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Updated methodology
    delete:
      summary: Delete a methodology
      operationId: kohnex_methodology_delete
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Deleted confirmation
  /api/v1/methodologies/{id}/fork:
    post:
      summary: Fork an existing methodology with custom changes
      operationId: kohnex_methodology_fork
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: {type: string}
                description: {type: string}
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      order: {type: integer}
                      name: {type: string}
                      description: {type: string}
                      knowledge_nodes: {type: array, items: {type: string}}
                      nature_pattern: {type: string}
                      principle: {type: string}
                tags: {type: array, items: {type: string}}
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Forked methodology
  /api/v1/explore:
    post:
      summary: Deep-explore the knowledge graph on any topic
      description: Runs multiple thinking modes, domain deep-dives, cross-domain path-finding, methodology matching, and nature/ancient/eureka synthesis in one call. Returns comprehensive exploration results.
      operationId: kohnex_explore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: Your question or topic to explore
                  maxLength: 4000
                depth:
                  type: string
                  description: Exploration depth (quick, auto, deep)
                  default: auto
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Comprehensive exploration with nodes, domains, paths, metaphors, and methodology
components:
  schemas: {}
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: khnx_<your_key>
      description: Get your API key at https://kohnex.com/pricing