Kagura AI Context Search Config API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Context Search Config API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: context-search-config
  description: Per-context search settings
paths:
  /api/v1/contexts/{context_id}/search-config:
    get:
      tags:
      - context-search-config
      summary: Get Context Search Config
      description: 'Get context search configuration.


        Retrieves hybrid search weights, fetch factor, and reranker settings for a context.


        Args:

        context_id: Context UUID

        current_user: Current authenticated user

        db: Database session


        Returns:

        ContextSearchConfigResponse with all settings


        Raises:

        HTTPException: 404 if context not found'
      operationId: get_context_search_config_api_v1_contexts__context_id__search_config_get
      parameters:
      - name: context_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Context 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/ContextSearchConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - context-search-config
      summary: Update Context Search Config
      description: 'Update context search configuration.


        Updates hybrid search weights, fetch factor, and/or reranker settings.

        Validates that weights sum to 1.0 and model matches provider.


        Context owners and editors may change every field except

        ``content_chunks_enabled`` and ``llm_selector_enabled``: changing either

        (on or off) takes the context owner or a workspace owner/admin, since

        turning it on sends memory content to the embedding and rerank providers

        (#2015) or to the deployment''s judge model at recall time (#2144). Sending

        the stored value is not a change and is allowed.


        Args:

        context_id: Context UUID

        update_data: Configuration update request

        current_user: Current authenticated user

        db: Database session


        Returns:

        Updated ContextSearchConfigResponse


        Raises:

        HTTPException: 400 if validation fails, 403 if the caller may not

        change content_chunks_enabled, 404 if context not found, 500 on error

        ValidationError: 422 when turning content_chunks_enabled on with the

        LanceDB vector store, which has no content chunk vectors (#2072)

        FeatureNotAvailableError: 403 ``FEAT-001`` when turning it on on a plan

        without ``content_chunks`` (only where CONTENT_CHUNKS_REQUIRE_PLAN

        is on, #2103)

        QuotaExceededError: 429 ``QUOTA-001`` when turning it on with the

        workspace at the plan''s ``max_content_chunk_contexts`` (likewise).

        The same 403 / 429 for ``llm_selector_enabled`` against

        ``llm_selector`` / ``max_llm_selector_contexts``, only where

        LLM_SELECTOR_REQUIRE_PLAN is on (#2144)'
      operationId: update_context_search_config_api_v1_contexts__context_id__search_config_put
      parameters:
      - name: context_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Context 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/ContextSearchConfigUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextSearchConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/contexts/{context_id}/search-config/reset:
    post:
      tags:
      - context-search-config
      summary: Reset Context Search Config
      description: 'Reset context search configuration to defaults.


        Resets all settings to default values:

        - semantic_weight: 0.6

        - bm25_weight: 0.4

        - fetch_factor: 3

        - use_rerank / reranker_provider / reranker_model: the deployment default

        (DEFAULT_USE_RERANK / DEFAULT_RERANKER_PROVIDER / DEFAULT_RERANKER_MODEL,

        #1572; unset: false / ''voyage'' / ''rerank-2'')

        - content_chunks_enabled: false — while it is on, that is a change and takes

        the context owner or a workspace owner/admin (#2015)

        - llm_selector_enabled: false — on the same rule (#2144)


        Args:

        context_id: Context UUID

        current_user: Current authenticated user

        db: Database session


        Returns:

        Reset ContextSearchConfigResponse


        Raises:

        HTTPException: 403 if content_chunks_enabled or llm_selector_enabled

        is on and the caller is not the context owner, 404 if context not

        found, 500 on error'
      operationId: reset_context_search_config_api_v1_contexts__context_id__search_config_reset_post
      parameters:
      - name: context_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Context 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/ContextSearchConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ContextSearchConfigUpdate:
      properties:
        semantic_weight:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Semantic Weight
          description: Semantic search weight
        bm25_weight:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Bm25 Weight
          description: BM25 keyword search weight
        fetch_factor:
          type: integer
          maximum: 10.0
          minimum: 1.0
          title: Fetch Factor
          description: Candidate retrieval multiplier
        use_rerank:
          type: boolean
          title: Use Rerank
          description: Enable/disable reranking
        reranker_provider:
          type: string
          title: Reranker Provider
          description: 'Reranker provider: ''voyage'', ''cohere'', or ''self_hosted'''
        reranker_model:
          type: string
          title: Reranker Model
          description: Provider-specific model name
        reinforce_enabled:
          type: boolean
          title: Reinforce Enabled
          description: Enable the bounded adoption+feedback recall re-rank
          default: true
        reinforce_max_boost:
          type: number
          maximum: 0.5
          minimum: 0.0
          title: Reinforce Max Boost
          description: Bound on the reinforce adjustment (factor stays in [1-b, 1+b])
          default: 0.15
        reinforce_require_host_arbitration:
          type: boolean
          title: Reinforce Require Host Arbitration
          description: Forge-resistant mode — only host-arbitrated feedback (provenance='host') moves ranking; an untrusted agent's self-feedback is ignored
          default: false
        routing_mode:
          type: string
          pattern: ^(off|log_only|active)$
          title: Routing Mode
          description: 'Query-intent router: off | log_only (stamp telemetry, zero ranking change) | active (routed lane used only when search_mode is omitted)'
          default: 'off'
        content_chunks_enabled:
          type: boolean
          title: Content Chunks Enabled
          description: 'Embed long content (>= 1500 chars) as chunk vectors so dense retrieval sees the body, not only the summary. Turning it on also queues the context''s existing long memories for chunking (drained in the background; see content_chunks_backfill_pending); turning it off deletes the chunks. When on, memory content (not only summaries) is sent to the embedding and rerank providers. Changing it takes the context owner or a workspace owner/admin (403 for an editor); sending the stored value is a no-op. Needs the Qdrant vector store: turning it on with LanceDB is refused (422)'
          default: false
        llm_selector_enabled:
          type: boolean
          title: Llm Selector Enabled
          description: 'Recall LLM selector opt-in: an MCP recall may send this context''s summaries and attached content to the deployment''s judge model, which keeps the results that answer the query and cuts their content to verbatim passages. Changing it takes the context owner or a workspace owner/admin (403 for an editor); sending the stored value is a no-op. Where the deployment gates it by plan (LLM_SELECTOR_REQUIRE_PLAN), turning it on needs the llm_selector feature (403 FEAT-001) and a free slot under max_llm_selector_contexts (429 QUOTA-001)'
          default: false
      type: object
      required:
      - semantic_weight
      - bm25_weight
      - fetch_factor
      - use_rerank
      - reranker_provider
      - reranker_model
      title: ContextSearchConfigUpdate
      description: 'Request schema for updating context search configuration.


        Issue #160: Renamed from ProjectSearchConfigUpdate to ContextSearchConfigUpdate'
    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
    ContextSearchConfigResponse:
      properties:
        context_id:
          title: Context Id
        semantic_weight:
          title: Semantic Weight
          description: Semantic search weight (0.0-1.0)
        bm25_weight:
          title: Bm25 Weight
          description: BM25 keyword search weight (0.0-1.0)
        fetch_factor:
          title: Fetch Factor
          description: Candidate retrieval multiplier (1-10)
        use_rerank:
          title: Use Rerank
          description: Enable/disable reranking
        reranker_provider:
          title: Reranker Provider
          description: Reranker provider (voyage/cohere)
        reranker_model:
          title: Reranker Model
          description: Provider-specific model name
        embedding_model:
          title: Embedding Model
          description: Embedding model (immutable)
        embedding_dimensions:
          title: Embedding Dimensions
          description: Vector dimensions (immutable)
        reinforce_enabled:
          title: Reinforce Enabled
          description: Bounded adoption+feedback recall re-rank enabled
        reinforce_max_boost:
          title: Reinforce Max Boost
          description: Bound on the reinforce adjustment (factor in [1-b, 1+b])
        reinforce_require_host_arbitration:
          title: Reinforce Require Host Arbitration
          description: Count only host-arbitrated (provenance='host') feedback
        routing_mode:
          title: Routing Mode
          description: 'Query-intent router: off | log_only (telemetry only) | active (opt-in)'
        content_chunks_enabled:
          title: Content Chunks Enabled
          description: Embed long content as chunk vectors for dense retrieval
        content_chunks_can_change:
          title: Content Chunks Can Change
          description: 'Whether the caller may change content_chunks_enabled: the context owner or a workspace owner/admin, and, to turn it on, a vector store that keeps chunk vectors and (where gated by plan) the plan''s feature and a free slot under its cap (#2103). Turning it off is always allowed'
        content_chunks_supported:
          title: Content Chunks Supported
          description: Whether the vector store keeps content chunk vectors (false on LanceDB)
        embedding_provider:
          title: Embedding Provider
          description: 'Provider of the context''s embedding model (openai / self_hosted): where memory content goes when content_chunks_enabled is on'
        content_chunks_backfill_pending:
          title: Content Chunks Backfill Pending
          description: Long memories (1,500+ characters) still waiting for their chunk vectors, e.g. the existing memories queued when the flag was turned on; 0 while it is off
        content_chunks_effective:
          title: Content Chunks Effective
          description: 'Whether the context''s content chunk vectors are read and written: content_chunks_enabled on, a vector store that keeps them, and, where the deployment gates them by plan (CONTENT_CHUNKS_REQUIRE_PLAN), a plan with the content_chunks feature on which this context is among the earliest-enabled max_content_chunk_contexts. An inactive context keeps the chunk vectors of unchanged memories; memories written or edited meanwhile get chunks only on their next edit or re-embed (nothing is re-queued when it becomes active again)'
        content_chunks_limit:
          title: Content Chunks Limit
          description: The workspace plan's max_content_chunk_contexts (0 without the content_chunks feature); null when the deployment does not gate content chunks by plan
        content_chunks_in_use:
          title: Content Chunks In Use
          description: Live contexts of the workspace with content_chunks_enabled on, this one included when it is on
        content_chunks_disabled_reason:
          title: Content Chunks Disabled Reason
          description: 'Why the toggle cannot be turned on (flag off) or why the chunks are inactive (flag on): unsupported (LanceDB), plan (the plan lacks content_chunks), cap (max_content_chunk_contexts reached), or permission (nothing else blocks, but only the context owner or a workspace owner/admin may change it); null when nothing blocks'
        llm_selector_enabled:
          title: Llm Selector Enabled
          description: 'Recall LLM selector opt-in: an MCP recall may send this context''s summaries and attached content to the deployment''s judge model, which keeps the results that answer the query and cuts their content to verbatim passages'
        llm_selector_effective:
          title: Llm Selector Effective
          description: 'Whether recall acts on llm_selector_enabled: on, and, where the deployment gates it by plan (LLM_SELECTOR_REQUIRE_PLAN), a plan with the llm_selector feature on which this context is among the earliest-enabled max_llm_selector_contexts'
        llm_selector_limit:
          title: Llm Selector Limit
          description: The workspace plan's max_llm_selector_contexts (0 without the llm_selector feature); null when the deployment does not gate the selector by plan
        llm_selector_in_use:
          title: Llm Selector In Use
          description: Live contexts of the workspace with llm_selector_enabled on, this one included when it is on
        llm_selector_disabled_reason:
          title: Llm Selector Disabled Reason
          description: 'Why the toggle cannot be turned on (flag off) or why the selector is inactive (flag on): plan (the plan lacks llm_selector), cap (max_llm_selector_contexts reached), or permission (nothing else blocks, but only the context owner or a workspace owner/admin may change it); null when nothing blocks'
        llm_selector_can_change:
          title: Llm Selector Can Change
          description: 'Whether the caller may change llm_selector_enabled: the context owner or a workspace owner/admin, and, to turn it on where gated by plan, the plan''s feature and a free slot under its cap. Turning it off is always allowed'
        created_at:
          title: Created At
        updated_at:
          title: Updated At
      type: object
      required:
      - context_id
      - semantic_weight
      - bm25_weight
      - fetch_factor
      - use_rerank
      - reranker_provider
      - reranker_model
      - embedding_model
      - embedding_dimensions
      - created_at
      - updated_at
      title: ContextSearchConfigResponse
      description: 'Response schema for context search configuration.


        Issue #130: Context-scoped Search & Reranker Settings

        Issue #146: Added immutable embedding configuration fields

        Issue #160: Renamed from Project to Context'