Kagura AI Agents API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Agents API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: Agents
  description: 'Agent Control Plane preview: workspace Agent Registry, subtractive context bindings, and composed session bootstrap'
paths:
  /api/v1/agents:
    post:
      tags:
      - Agents
      summary: Register Agent
      description: Register an agent in the active workspace (owner/admin only).
      operationId: register_agent_api_v1_agents_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agents
      summary: List Agents
      description: List the active workspace's registered agents (owner/admin only).
      operationId: list_agents_api_v1_agents_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/AgentListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}:
    get:
      tags:
      - Agents
      summary: Get Agent
      description: Fetch one registered agent (owner/admin only).
      operationId: get_agent_api_v1_agents__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - 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/AgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Agents
      summary: Update Agent
      description: Partially update an agent, including status / enforcement transitions.
      operationId: update_agent_api_v1_agents__agent_id__patch
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agents
      summary: Delete Agent
      description: 'Hard-delete a registry row (owner/admin only).


        Operational retirement should normally use ``status=''retired''``; hard

        delete stays available and (from P0-2 on) cascades every bound key.'
      operationId: delete_agent_api_v1_agents__agent_id__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}/bindings:
    post:
      tags:
      - Agents
      summary: Create Agent Binding
      description: Bind an agent to a context (owner/admin only, purely subtractive).
      operationId: create_agent_binding_api_v1_agents__agent_id__bindings_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindingCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agents
      summary: List Agent Bindings
      description: List an agent's context bindings (owner/admin only).
      operationId: list_agent_bindings_api_v1_agents__agent_id__bindings_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - 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/BindingListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}/bindings/{binding_id}:
    patch:
      tags:
      - Agents
      summary: Update Agent Binding
      description: Partially update a binding (owner/admin only).
      operationId: update_agent_binding_api_v1_agents__agent_id__bindings__binding_id__patch
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: binding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Binding Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindingUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agents
      summary: Delete Agent Binding
      description: Delete a binding (owner/admin only) — the agent loses that context.
      operationId: delete_agent_binding_api_v1_agents__agent_id__bindings__binding_id__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: binding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Binding Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/{agent_id}/bootstrap:
    post:
      tags:
      - Agents
      summary: Agent Bootstrap
      description: 'Rehydrate an agent''s cognitive state at session start (#1276).


        Auth is ``APIKeyOrSessionUser``; the per-request agent scope (set at

        API-key verify for agent-bound keys) drives the identity rule inside the

        service. Component failures are fail-soft; identity/authorization failures

        are total and fail-closed with the uniform ``agent_not_found`` /

        ``context_not_found`` shapes.'
      operationId: agent_bootstrap_api_v1_agents__agent_id__bootstrap_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BootstrapRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Agent Bootstrap Api V1 Agents  Agent Id  Bootstrap Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BindingUpdate:
      properties:
        can_read:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Can Read
        write_policy:
          anyOf:
          - type: string
            enum:
            - deny
            - direct
          - type: 'null'
          title: Write Policy
        is_default:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Default
        allowed_memory_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Memory Types
          description: 'Per-memory type filter (#1299): null = all types, [] = deny-all'
        allowed_source_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Source Types
          description: 'Per-memory source filter (#1299): null = all sources, [] = deny-all'
      type: object
      title: BindingUpdate
      description: Partial binding update (``context_id`` is immutable — recreate to re-target).
    BootstrapRequest:
      properties:
        context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Context Id
        session_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Session Id
        query:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Query
        recall_k:
          anyOf:
          - type: integer
          - type: 'null'
          title: Recall K
        pinned_cap:
          anyOf:
          - type: integer
          - type: 'null'
          title: Pinned Cap
        upcoming_until:
          anyOf:
          - type: string
          - type: 'null'
          title: Upcoming Until
        include:
          anyOf:
          - items:
              type: string
              enum:
              - pinned
              - recall
              - upcoming
              - state
              - policy
            type: array
          - type: 'null'
          title: Include
        recall_evaluation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Recall Evaluation
        max_chars:
          anyOf:
          - type: integer
            maximum: 100000.0
            minimum: 10000.0
          - type: 'null'
          title: Max Chars
      type: object
      title: BootstrapRequest
      description: 'Body for POST /api/v1/agents/{agent_id}/bootstrap (agent_id from path).


        POST-for-read follows the POST /api/v1/memory/pinned precedent.'
    AgentCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Workspace-unique name
        description:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Description
        framework:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Framework
          description: 'Free-form: ''claude-code'', ''langgraph'', ...'
        environment:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Environment
          description: Aligned with OTel deployment.environment.name
        version:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Version
          description: Agent build/prompt version (client-reported)
      type: object
      required:
      - name
      title: AgentCreate
      description: Request model for registering an agent.
    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
    BindingCreate:
      properties:
        context_id:
          type: string
          format: uuid
          title: Context Id
        can_read:
          type: boolean
          title: Can Read
          default: true
        write_policy:
          type: string
          enum:
          - deny
          - direct
          title: Write Policy
          default: deny
        is_default:
          type: boolean
          title: Is Default
          description: Bootstrap default binding (max one per agent)
          default: false
        allowed_memory_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Memory Types
          description: 'Per-memory type filter (#1299): null = all types, [] = deny-all, else the memory types this binding may read (enforce-mode only). Applies to the memory-read lanes; enumeration/aggregate surfaces still use the context-level gate until #1301'
        allowed_source_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Source Types
          description: 'Per-memory source filter (#1299): null = all sources, [] = deny-all, else values from the memories.source_type set. Applies to the memory-read lanes; enumeration/aggregate surfaces still use the context-level gate until #1301'
      type: object
      required:
      - context_id
      title: BindingCreate
      description: Request model for binding an agent to a context (subtractive scoping).
    AgentResponse:
      properties:
        id:
          title: Id
        workspace_id:
          title: Workspace Id
        name:
          title: Name
        description:
          title: Description
        owner_user_id:
          title: Owner User Id
        framework:
          title: Framework
        environment:
          title: Environment
        version:
          title: Version
        status:
          title: Status
        enforcement_mode:
          title: Enforcement Mode
        last_seen_at:
          title: Last Seen At
        created_at:
          title: Created At
        updated_at:
          title: Updated At
      type: object
      required:
      - id
      - workspace_id
      - name
      - owner_user_id
      - status
      - enforcement_mode
      - created_at
      - updated_at
      title: AgentResponse
      description: Response model for one registry row.
    AgentListResponse:
      properties:
        agents:
          items:
            $ref: '#/components/schemas/AgentResponse'
          type: array
          title: Agents
        count:
          type: integer
          title: Count
      type: object
      required:
      - agents
      - count
      title: AgentListResponse
      description: Response model for the workspace agent listing.
    BindingResponse:
      properties:
        id:
          title: Id
        agent_id:
          title: Agent Id
        context_id:
          title: Context Id
        can_read:
          title: Can Read
        write_policy:
          title: Write Policy
        is_default:
          title: Is Default
        allowed_memory_types:
          title: Allowed Memory Types
        allowed_source_types:
          title: Allowed Source Types
        created_by:
          title: Created By
        created_at:
          title: Created At
        updated_at:
          title: Updated At
      type: object
      required:
      - id
      - agent_id
      - context_id
      - can_read
      - write_policy
      - is_default
      - created_by
      - created_at
      - updated_at
      title: BindingResponse
      description: Response model for one binding row.
    BindingListResponse:
      properties:
        bindings:
          items:
            $ref: '#/components/schemas/BindingResponse'
          type: array
          title: Bindings
        count:
          type: integer
          title: Count
      type: object
      required:
      - bindings
      - count
      title: BindingListResponse
      description: Response model for an agent's binding listing.
    AgentUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Description
        framework:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Framework
        environment:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Environment
        version:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Version
        status:
          anyOf:
          - type: string
            enum:
            - active
            - suspended
            - retired
          - type: 'null'
          title: Status
          description: Lifecycle kill switch (fail-closed for bound keys, P0-2)
        enforcement_mode:
          anyOf:
          - type: string
            enum:
            - shadow
            - enforce
          - type: 'null'
          title: Enforcement Mode
          description: Binding enforcement ramp; enforce→shadow is audited as widening
      type: object
      title: AgentUpdate
      description: 'Request model for a partial agent update.


        Only fields explicitly present in the request body are applied

        (``exclude_unset``), so ``null`` clears a metadata field while an absent

        key leaves it untouched.'