Kagura AI Public Search API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Public Search API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: public-search
  description: Public REST API for search
paths:
  /api/v1/public/{context_id}/search:
    post:
      tags:
      - public-search
      summary: Public Search
      description: 'Search public context with schema-aware response formatting.


        Issue #238: Public REST API for external systems (EC inventory, docs, etc.).

        Issue #626: Optional API-key attribution via ``Authorization: Bearer

        ``. A bound key gets a per-key rate-limit bucket and audit

        attribution; an unbound key (owner / workspace-scoped) is rejected so

        callers don''t accidentally route their primary credentials through a

        public path. Anonymous access continues to work without any header.


        Authentication:

        - Workspace member session (authenticated access, no rate limit)

        - Public-bound API key (#626) — per-key rate limit, audit-attributed

        - Anonymous access (rate limited to 50 req/min per context, shared)


        Rate Limits:

        - Anonymous access: 50 requests/minute per context (shared bucket)

        - Public-bound key: per-key bucket from workspace plan tier

        (``bound_public_calls_per_minute``)

        - Workspace members: No limit (uses normal workspace quota)


        Request:

        POST /api/v1/public/{context_id}/search

        Headers:

        Authorization: Bearer kagura_… (optional; required only for

        attributed/bound-key access)

        Body:

        {

        "query": "商品名 価格",

        "limit": 10,

        "use_rerank": false

        }


        Response:

        {

        "status": "success",

        "query": "商品名 価格",

        "results": [

        {

        "memory_id": "...",

        "content": "商品名: ..., 価格: ...",

        "score": 0.95,

        "metadata": {...},

        "highlighted": {...}

        }

        ],

        "count": 5,

        "context_id": "...",

        "resource_id": "ec_products",

        "schema_version": 1

        }


        Errors:

        - 401: API key supplied but invalid / expired

        - 403: Context is not public, OR API key is not public-bound, OR

        API key is bound to a different context (CWE-639 IDOR)

        - 404: Context not found

        - 429: Rate limit exceeded (anonymous or per-key bucket), or the

        workspace''s plan has no public API allowance (#1939)'
      operationId: public_search_api_v1_public__context_id__search_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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/public/{context_id}/info:
    get:
      tags:
      - public-search
      summary: Get Public Context Info
      description: 'Get public context metadata and schema information.


        Returns basic information about the public context including:

        - Context name and description

        - Resource schema (if resource-backed)

        - Statistics (memory count, last updated)


        Issue #626: An optional ``Authorization: Bearer `` is accepted

        for symmetry with ``/search``. The same IDOR guard applies — a key

        bound to a different context is rejected with 403 — but no rate limit

        or audit attribution is applied here because ``/info`` returns only

        static metadata (no memory contents).


        Args:

        context_id: Context UUID

        api_key: Optional public-bound API key (Issue #626).

        db: Database session


        Returns:

        Public context metadata


        Errors:

        - 401: API key supplied but invalid / expired

        - 403: Context is not public, OR API key is not public-bound, OR

        API key is bound to a different context (CWE-639 IDOR)

        - 404: Context not found

        - 429: The workspace''s plan has no public API allowance (#1939)'
      operationId: get_public_context_info_api_v1_public__context_id__info_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: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PublicSearchRequest:
      properties:
        query:
          type: string
          maxLength: 500
          minLength: 1
          title: Query
          description: Search query
        limit:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          description: 'Maximum results (default: 10, max: 100)'
          default: 10
        use_rerank:
          type: boolean
          title: Use Rerank
          description: Enable reranking for better results
          default: false
        search_mode:
          type: string
          pattern: ^(hybrid|semantic|keyword)$
          title: Search Mode
          description: 'Search mode: hybrid (default), semantic, keyword'
          default: hybrid
      type: object
      required:
      - query
      title: PublicSearchRequest
      description: Public search request.
    PublicSearchResult:
      properties:
        memory_id:
          type: string
          title: Memory Id
        content:
          type: string
          title: Content
        score:
          type: number
          title: Score
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        highlighted:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Highlighted
      type: object
      required:
      - memory_id
      - content
      - score
      - metadata
      title: PublicSearchResult
      description: Single search result with schema-aware formatting.
    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
    PublicSearchResponse:
      properties:
        status:
          type: string
          title: Status
          default: success
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/PublicSearchResult'
          type: array
          title: Results
        count:
          type: integer
          title: Count
        context_id:
          type: string
          title: Context Id
        resource_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource Id
        schema_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Schema Version
        degraded:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Degraded
        degraded_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Degraded Reason
      type: object
      required:
      - query
      - results
      - count
      - context_id
      title: PublicSearchResponse
      description: Public search response.