openapi: 3.1.0
info:
  title: EdgeHub Memory API
  description: |
    API for interacting with EdgeHub's distributed memory system, Lattices, and AI capabilities.
    This API allows agents and applications to store, retrieve, and analyze data across the EdgeHub network.
  version: 1.0.2.2504302214
  contact:
    name: EdgeHub Support
    url: https://fractalstones.vercel.app/support
servers:
  - url: https://fractalstones.vercel.app
    description: Production server
paths:
  /api/memory:
    get:
      summary: Retrieve a value from memory
      description: Get a value stored in memory by its key
      operationId: getMemoryValue
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: query
          description: The key to retrieve
          required: true
          schema:
            type: string
        - name: list
          in: query
          description: If true, lists all keys (writer token required)
          required: false
          schema:
            type: boolean
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/MemoryValue'
                  - $ref: '#/components/schemas/KeysList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: Store a value in memory
      description: Store a key-value pair in memory (writer token required)
      operationId: storeMemoryValue
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key
                - value
              properties:
                key:
                  type: string
                  description: The key to store the value under
                value:
                  type: [string, number, boolean, object, array]
                  description: The value to store
      responses:
        '200':
          description: Value stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/memory/meta:
    get:
      summary: Retrieve metadata about a key
      description: Get metadata about a key without retrieving its full value
      operationId: getKeyMetadata
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: query
          description: The key to retrieve metadata for
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/lattices/{key}:
    get:
      summary: Retrieve a Lattice (plural form)
      description: Get a Lattice by its key using the plural form
      operationId: getLattice
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: path
          description: The Lattice key (without the 'lattices:' prefix)
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatticeValue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: Store a Lattice (plural form)
      description: Store a Lattice value using the plural form (writer token required)
      operationId: storeLattice
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: path
          description: The Lattice key (without the 'lattices:' prefix)
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - value
              properties:
                value:
                  type: [string, number, boolean, object, array]
                  description: The value to store
      responses:
        '200':
          description: Lattice stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatticeStoreResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/lattice/{key}:
    get:
      summary: Retrieve a Lattice (singular form)
      description: Get a Lattice by its key using the singular form
      operationId: getLatticeS
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: path
          description: The Lattice key (without the 'lattice:' prefix)
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatticeValue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: Store a Lattice (singular form)
      description: Store a Lattice value using the singular form (writer token required)
      operationId: storeLatticeS
      x-openai-isConsequential: false
      parameters:
        - name: key
          in: path
          description: The Lattice key (without the 'lattice:' prefix)
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - value
              properties:
                value:
                  type: [string, number, boolean, object, array]
                  description: The value to store
      responses:
        '200':
          description: Lattice stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatticeStoreResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/scan:
    get:
      summary: Scan for keys matching a pattern
      description: Retrieve keys matching a pattern or regex
      operationId: scanKeys
      x-openai-isConsequential: false
      parameters:
        - name: pattern
          in: query
          description: Redis glob pattern to match keys
          required: false
          schema:
            type: string
        - name: regex
          in: query
          description: Regular expression to match keys (writer token only)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of keys to return
          required: false
          schema:
            type: integer
            default: 4100
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/forge-state:
    get:
      summary: Get forge state
      description: Check if the forge is open or closed (writer token required)
      operationId: getForgeState
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgeState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: Update forge state
      description: Open or close the forge (writer token required)
      operationId: updateForgeState
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - state
              properties:
                state:
                  type: boolean
                  description: True to open the forge, false to close it
      responses:
        '200':
          description: Forge state updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgeState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/ai:
    post:
      summary: Generate AI completion
      description: Generate text using OpenAI models (writer token required)
      operationId: generateCompletion
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
  
  /api/ai/models:
    get:
      summary: List available AI models
      description: Get a list of available AI models (writer token required)
      operationId: listAIModels
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Specific model ID to retrieve
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AIModelsList'
                  - $ref: '#/components/schemas/AIModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/ai/roles:
    get:
      summary: List available AI roles
      description: Get a list of available AI roles (writer token required)
      operationId: listAIRoles
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Specific role ID to retrieve
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AIRolesList'
                  - $ref: '#/components/schemas/AIRole'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: Create or update an AI role
      description: Create a new AI role or update an existing one (writer token required)
      operationId: createUpdateAIRole
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIRole'
      responses:
        '200':
          description: Role saved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    $ref: '#/components/schemas/AIRole'
                  timestamp:
                    type: string
                    format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      summary: Delete an AI role
      description: Delete an AI role by ID (writer token required)
      operationId: deleteAIRole
      x-openai-isConsequential: false
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Role ID to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Role deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: Reader or writer token for API authentication
  
  schemas:
    MemoryValue:
      type: object
      properties:
        key:
          type: string
          description: The key that was retrieved
        value:
          type: [string, number, boolean, object, array]
          description: The stored value
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
    
    KeyMetadata:
      type: object
      properties:
        key:
          type: string
          description: The key that was queried
        exists:
          type: boolean
          description: Whether the key exists
        ttl:
          type: [integer, "null"]
          description: Time to live in seconds, null if no expiration
        type:
          type: string
          description: Inferred type based on key pattern
          enum: [redstone, lattice, forge, current, unknown]
        preview:
          type: [string, "null"]
          description: Preview of the value (first 120 characters if string)
        lastModified:
          type: string
          format: date-time
          description: Timestamp of when the metadata was retrieved
    
    KeysList:
      type: object
      properties:
        keys:
          type: array
          items:
            type: string
          description: List of keys in the database
        count:
          type: integer
          description: Number of keys returned
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
    
    StoreResponse:
      type: object
      properties:
        key:
          type: string
          description: The key that was stored
        value:
          type: [string, number, boolean, object, array]
          description: The value that was stored
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the storage operation
        message:
          type: string
          description: Success message
    
    RedStoneValue:
      type: object
      properties:
        key:
          type: string
          description: The RedStone key (without prefix)
        value:
          type: [string, number, boolean, object, array]
          description: The stored RedStone value
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
    
    RedStoneStoreResponse:
      type: object
      properties:
        key:
          type: string
          description: The RedStone key (without prefix)
        value:
          type: [string, number, boolean, object, array]
          description: The value that was stored
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the storage operation
        message:
          type: string
          description: Success message
    
    LatticeValue:
      type: object
      properties:
        key:
          type: string
          description: The Lattice key (without prefix)
        value:
          type: [string, number, boolean, object, array]
          description: The stored Lattice value
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
    
    LatticeStoreResponse:
      type: object
      properties:
        key:
          type: string
          description: The Lattice key (without prefix)
        value:
          type: [string, number, boolean, object, array]
          description: The value that was stored
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the storage operation
        message:
          type: string
          description: Success message
    
    ScanResponse:
      type: object
      properties:
        pattern:
          type: string
          description: The pattern that was used for scanning
        regex:
          type: string
          description: The regex pattern that was used (if applicable)
        keys:
          type: array
          items:
            type: string
          description: List of matching keys
        count:
          type: integer
          description: Number of keys returned
        limit:
          type: integer
          description: Maximum number of keys that could be returned
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the scan operation
    
    ForgeState:
      type: object
      properties:
        isOpen:
          type: boolean
          description: Whether the forge is open
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the operation
        message:
          type: string
          description: Status message (only in POST response)
    
    AIRequest:
      type: object
      required:
        - prompt
      properties:
        modelId:
          type: string
          description: ID of the model to use (uses default if not specified)
        prompt:
          type: string
          description: The prompt to generate completion for
        maxTokens:
          type: integer
          description: Maximum number of tokens to generate
        temperature:
          type: number
          format: float
          minimum: 0
          maximum: 2
          description: Sampling temperature (0-2)
        rolesystem:
          type: string
          description: Custom system instructions for the AI role (overrides roleid if both are provided)
        roleid:
          type: string
          description: ID of a predefined role to use (ignored if rolesystem is provided)
    
    AIResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique ID for the completion
        model:
          type: string
          description: The model used for completion
        choices:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                description: Generated text
              index:
                type: integer
                description: Choice index
              finish_reason:
                type: string
                description: Reason for finishing (e.g., "stop", "length")
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              description: Number of tokens in the prompt
            completion_tokens:
              type: integer
              description: Number of tokens in the completion
            total_tokens:
              type: integer
              description: Total number of tokens used
        role:
          type: object
          properties:
            id:
              type: string
              description: ID of the role used
            system:
              type: string
              description: System instructions used for this completion
    
    AIModel:
      type: object
      properties:
        id:
          type: string
          description: Model ID
        name:
          type: string
          description: Display name
        provider:
          type: string
          description: Model provider (e.g., "OpenAI")
        providerId:
          type: string
          description: Provider-specific ID
        enabled:
          type: boolean
          description: Whether the model is enabled
    
    AIModelsList:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/AIModel'
        count:
          type: integer
          description: Number of models returned
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
    
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code (if applicable)
    AIRole:
      type: object
      required:
        - id
        - name
        - rolesystem
      properties:
        id:
          type: string
          description: Unique identifier for the role
        name:
          type: string
          description: Display name for the role
        rolesystem:
          type: string
          description: System instructions for the AI when using this role
    AIRolesList:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/AIRole'
        count:
          type: integer
          description: Number of roles returned
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the retrieval
  
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'