Kagura AI Workers API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Workers API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: Workers
  description: Authenticated connector-worker runtime configuration and deployment discovery
paths:
  /api/v1/workers/apps:
    get:
      tags:
      - Workers
      summary: Get Worker Apps
      description: 'Bootstrap app identities and signing secrets over the internal lane.


        This service token grants no memory authority. Disabled/unconfigured apps

        remain in the list without secret material so a polling worker can evict

        stale verification state deterministically.'
      operationId: get_worker_apps_api_v1_workers_apps_get
      parameters:
      - name: If-None-Match
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerAppBootstrapResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workers/config:
    get:
      tags:
      - Workers
      summary: Get Worker Config
      description: 'Return the connector config for a platform team (worker dispatch).


        404 when no connector serves the team, the connector has no write-target

        context yet (registration incomplete) or that context was soft-deleted or

        is no longer in the connector''s workspace, its workspace''s plan has connectors

        suspended (#1939), it has no KMC write key, its

        ``llm_config`` cannot vend (#1447), or it uses channel routing and the

        worker did not declare the ``channel_routes`` capability (#1759) — the

        worker treats all of them as not-ready and skips the team rather than

        failing the dispatch.'
      operationId: get_worker_config_api_v1_workers_config_get
      parameters:
      - name: platform
        in: query
        required: true
        schema:
          const: slack
          type: string
          title: Platform
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 255
          title: Team Id
      - name: app_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 64
            pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
          - type: 'null'
          title: App Key
      - name: capabilities
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          description: 'Comma-separated contract features the worker implements; unknown tokens are ignored. `channel_routes` (#1759): the worker honours per-channel destinations, and the body carries `channel_routes` and `unrouted_private_channels`. Without it, a connector that uses routing is not ready (404).'
          title: Capabilities
        description: 'Comma-separated contract features the worker implements; unknown tokens are ignored. `channel_routes` (#1759): the worker honours per-channel destinations, and the body carries `channel_routes` and `unrouted_private_channels`. Without it, a connector that uses routing is not ready (404).'
      - name: If-None-Match
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerConnectorConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workers/active-color:
    get:
      tags:
      - Workers
      summary: Live blue-green deploy color
      description: 'Report the color serving traffic, read from the deploy marker per request.


        A co-resident consumer of this lane used to learn the live color by

        bind-mounting the marker file itself, which pins the inode at container

        start and silently goes stale (#1482). Here the process that owns the

        marker reads it on every call, so the answer is always the marker''s

        current value. ``responding_color`` is the identity of the instance that

        answered: when it differs from ``active_color`` the caller has reached a

        color that is no longer live and should re-target.'
      operationId: get_active_color_api_v1_workers_active_color_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerActiveColorResponse'
        '503':
          description: The deploy marker is missing, unreadable or not a known color (error code DEPLOY-001, ``details.reason`` = missing | unreadable | invalid). No color is guessed. Every reason can be transient while the marker is republished during a color switch — treat the 503 as retryable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WorkerAppBootstrapItem:
      properties:
        app_key:
          title: App Key
        platform:
          title: Platform
        status:
          title: Status
        revision:
          title: Revision
        active: {}
        retiring: {}
      type: object
      required:
      - app_key
      - platform
      - status
      - revision
      title: WorkerAppBootstrapItem
      description: One app identity. Secrets are present only while the app is active.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WorkerActiveColorResponse:
      properties:
        active_color:
          type: string
          enum:
          - blue
          - green
          title: Active Color
        responding_color:
          anyOf:
          - type: string
            enum:
            - blue
            - green
          - type: 'null'
          title: Responding Color
      type: object
      required:
      - active_color
      - responding_color
      title: WorkerActiveColorResponse
      description: Which blue-green color is live, and which one answered (#1482).
    WorkerAppBootstrapResponse:
      properties:
        revision:
          type: string
          title: Revision
        apps:
          items:
            $ref: '#/components/schemas/WorkerAppBootstrapItem'
          type: array
          title: Apps
      type: object
      required:
      - revision
      - apps
      title: WorkerAppBootstrapResponse
    WorkerConnectorConfig:
      additionalProperties: true
      type: object