Kagura AI Share Keys API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Share Keys API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: share-keys
  description: Share-key lifecycle, public recall, and share-session inspection
paths:
  /api/v1/config/share-keys:
    post:
      tags:
      - share-keys
      summary: Create Share Key
      description: 'Mint a read-only, TTL-bounded share key for one owned context (#1027).


        The caller must OWN ``context_id`` — enforced via

        ``check_context_access(..., OWNER)``, which raises a uniform 404 if the

        context does not exist or the caller cannot reach it, and 403 if the

        caller reaches it without owner rights. This prevents minting a share

        key for a context the user cannot administer.'
      operationId: create_share_key_api_v1_config_share_keys_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/ShareKeyCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareKeyCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - share-keys
      summary: List Share Keys
      description: List the current user's share keys (newest first).
      operationId: list_share_keys_api_v1_config_share_keys_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:
                type: array
                items:
                  $ref: '#/components/schemas/ShareKeyResponse'
                title: Response List Share Keys Api V1 Config Share Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/share-keys/{key_id}/revoke:
    post:
      tags:
      - share-keys
      summary: Revoke Share Key
      description: Revoke a share key (soft delete; uniform 404 if not the user's active key).
      operationId: revoke_share_key_api_v1_config_share_keys__key_id__revoke_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^skey_[0-9A-Za-z]{22}$
          description: Public id of the share key (`skey_` + 22 base62 characters).
          examples:
          - skey_0000000000000000000000
          title: Key Id
        description: Public id of the share key (`skey_` + 22 base62 characters).
      - 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/share/recall:
    post:
      tags:
      - share-keys
      summary: Share Recall
      description: 'Recall confined to the share key''s bound context (#1027).


        The bound context (and its workspace) come from the verified share key —

        never from the request or the owner''s current workspace. A client-supplied

        ``filters.context_id`` that differs from the bound context is rejected

        (BOUND_SCOPE_VIOLATION), and otherwise recall is forced to the bound

        context so cross-context read is structurally impossible (#963/#150).'
      operationId: share_recall_api_v1_share_recall_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/RecallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/share/sessions:
    get:
      tags:
      - share-keys
      summary: Share Sessions
      description: 'List the bound context''s live agent session-state, read-only (#1064).


        A **read-only projection** of the #889/#906 agent session-state lane,

        driven by a #1027 share key and confined to the key''s bound context — so an

        external, observe-only dashboard can render live agent status without

        holding a privileged credential and without the agent dialling out.


        Confinement and read-only-ness are structural (inherited from #1027): the

        context comes from the verified share key (never the request), and write /

        control verbs on the lane (`PUT`/`DELETE /contexts/{id}/state`) authenticate

        against `api_keys` — a share key is rejected there outright. Approvals stay

        on the cockpit/Slack operator path; this surface can only *observe*.'
      operationId: share_sessions_api_v1_share_sessions_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/SharedSessionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RecallRequest:
      properties:
        query:
          type: string
          maxLength: 8000
          minLength: 1
          title: Query
          description: 検索クエリ
        k:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: K
          description: 返却結果数
          default: 5
        use_rerank:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Use Rerank
          description: Reranking (Voyage/Cohere BYOK, or self_hosted). Omit to follow the context's search config; set false to force off.
        filters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Filters
          description: オプショナルフィルタ
        search_mode:
          anyOf:
          - type: string
            pattern: ^(hybrid|semantic|keyword)$
          - type: 'null'
          title: Search Mode
          description: 'Search mode: hybrid (default when omitted), semantic (vector only), keyword (BM25 only). Omit to allow query-intent routing on contexts with routing_mode=''active'' (#1212).'
        include_explore_hints:
          type: boolean
          title: Include Explore Hints
          description: Include up to 3 explore_hints in response suggesting good seeds for explore()
          default: false
        include_superseded:
          type: boolean
          title: Include Superseded
          description: Include memories shadowed by a supersedes edge (annotated with superseded_by) and return folded older versions as their own rows
          default: false
        full:
          anyOf:
          - type: integer
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Full
          description: How many of the top results carry content, each cut at 1,500 characters (content_truncated / content_next_offset when cut). Omit or 0 for summaries only.
      type: object
      required:
      - query
      title: RecallRequest
      description: "Request schema for recall() API (Hybrid Search).\n\nExample:\n    {\n        \"query\": \"認証エラーの解決方法\",\n        \"k\": 5,\n        \"use_rerank\": false,\n        \"filters\": {\n            \"context_id\": \"my-context\",\n            \"scope\": \"persistent\",\n            \"type\": \"code\"\n        }\n    }"
    ShareKeyCreate:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Friendly name
        context_id:
          type: string
          format: uuid
          title: Context Id
          description: The single context to confine the key to (must be owned)
        ttl_days:
          anyOf:
          - type: integer
            maximum: 3650.0
            minimum: 1.0
          - type: 'null'
          title: Ttl Days
          description: Requested lifetime in days. Clamped server-side to a 30-day ceiling; omit for the 30-day default.
      type: object
      required:
      - name
      - context_id
      title: ShareKeyCreate
      description: Request to mint a share key bound to one owned context.
    SharedSessionsResponse:
      properties:
        sessions:
          title: Sessions
          description: Live entries, most recent first
        count:
          title: Count
          description: Number of live entries
        as_of:
          title: As Of
          description: Server time this snapshot was read
      type: object
      required:
      - sessions
      - count
      - as_of
      title: SharedSessionsResponse
      description: The bound context's live agent session-state, for a status board (#1064).
    ExploreHint:
      properties:
        memory_id:
          type: string
          format: uuid
          title: Memory Id
        reason:
          type: string
          enum:
          - top_result
          - high_centrality
          - unexplored_neighbor
          title: Reason
      type: object
      required:
      - memory_id
      - reason
      title: ExploreHint
      description: 'Hint suggesting a memory as a good seed for explore().


        Issue #216: Opt-in field to bridge recall → explore discovery.'
    RelatedTagItem:
      properties:
        tag:
          title: Tag
        count:
          title: Count
        sample_summary:
          title: Sample Summary
        last_used_at:
          title: Last Used At
      type: object
      required:
      - tag
      - count
      title: RelatedTagItem
      description: 'Related tag with count, sample summary, and last-used timestamp.


        Used by ``recall.related_tags`` (Issue #104 — populates ``sample_summary``)

        and ``list_tags`` (Issue #614 — populates ``last_used_at``). The shared

        schema means clients can unify their "tag info" type across both surfaces.

        Inherits ``TZAwareBaseModel`` so the optional ``last_used_at`` serializes

        with an explicit UTC ``Z`` suffix when populated.'
    RecallResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/MemoryResponse'
          type: array
          title: Results
        related_tags:
          items:
            $ref: '#/components/schemas/RelatedTagItem'
          type: array
          title: Related Tags
          default: []
        explore_hints:
          anyOf:
          - items:
              $ref: '#/components/schemas/ExploreHint'
            type: array
          - type: 'null'
          title: Explore Hints
        tag_suggestions:
          anyOf:
          - additionalProperties:
              items:
                type: string
              type: array
            type: object
          - type: 'null'
          title: Tag Suggestions
          description: 'Tags present in this context that resemble the ones filtered on, keyed by the requested tag. Present only when a tag filter matched no memories. Advisory: the filter itself was not widened.'
        confidence:
          anyOf:
          - $ref: '#/components/schemas/RecallConfidence'
          - type: 'null'
        degraded:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Degraded
          description: True when this result set was produced without the semantic search arm. Absent when the search ran normally.
        degraded_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Degraded Reason
          description: 'Why the search degraded: ''embedding_unavailable'' (the embedding provider failed) or ''vector_search_unavailable'' (the vector store failed). Absent when the search ran normally.'
        selector:
          anyOf:
          - $ref: '#/components/schemas/SelectorReport'
          - type: 'null'
      type: object
      required:
      - results
      title: RecallResponse
      description: 'Response schema for recall() API.


        Issue #104: Added related_tags to help LLMs understand tag context.

        Issue #216: Added explore_hints for graph discovery bridging.

        Issue #1047: Added confidence (relevance/staleness signal) — additive.'
    RecallConfidence:
      properties:
        level:
          type: string
          enum:
          - high
          - moderate
          - low
          - none
          title: Level
        top_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Top Score
          description: Raw semantic cosine of the best hit (absolute match strength, 0-1). On keyword-only searches this is the normalized hybrid top instead.
        prominence:
          anyOf:
          - type: number
          - type: 'null'
          title: Prominence
          description: (top_score - mean_background_cosine) / mean_background_cosine — a model-scale-invariant match prominence and the primary basis for level. None when <2 candidates or keyword-only.
        relative_margin:
          anyOf:
          - type: number
          - type: 'null'
          title: Relative Margin
          description: Separation of the top hit from the candidate-pool background, in background std-devs. Informational only — it inflates on flat off-topic tails and is not used for level. None when <2 candidates.
        result_count:
          type: integer
          title: Result Count
        rationale:
          type: string
          title: Rationale
      type: object
      required:
      - level
      - result_count
      - rationale
      title: RecallConfidence
      description: "Issue #1047/#1052: a signal distinguishing \"relevant results found\" from\n\"likely nothing relevant\" (so an agent can stop probing / go external instead\nof trusting a weak hit), WITHOUT changing ranking.\n\n``level`` is driven by **absolute semantic match strength**, made robust to\nembedding-model scale via ``prominence`` (#1052):\n\n- ``top_score`` — the RAW semantic cosine of the best hit (absolute match\n  strength in [0, 1]). High ⇒ something closely matches the query.\n- ``prominence`` — ``(top_score - mean_background_cosine) /\n  mean_background_cosine`` over the candidate pool. A *ratio*, so it is\n  invariant to the overall cosine scale a given embedding model produces\n  (text-embedding-3-small and qwen3-embedding sit at different absolute\n  cosines, but a real match is proportionally far above its background in\n  both). ``level`` thresholds on this; a near-duplicate ``top_score`` floors\n  ``level`` to at least ``moderate``.\n\nHow an agent should use it (it is a TRIAGE hint, not a correctness verdict):\n\n- ``none`` / ``low`` → likely nothing relevant; prefer an external source over\n  forcing an answer out of these results. This is the high-value signal and is\n  reliable without a reranker.\n- ``high`` / ``moderate`` → relevant memory is likely present; READ the returned\n  summaries and judge from their content. ``level`` measures *topical match\n  strength*, so a closely-related \"near-miss\" (an adjacent topic) can also read\n  ``high`` — it does NOT guarantee the exact fact you asked for is stored. The\n  returned content is the source of truth; ``level`` only says whether it is\n  worth reading. Distinguishing near-miss from an exact match needs a\n  cross-encoder (pass ``use_rerank=true``); plain bi-encoder cosine cannot.\n\nWhy this supersedes the original #1047 z-score approach: that bucketed on\n``relative_margin`` (background std-devs), but max-normalization in the hybrid\nmerge erases absolute strength, and dividing by a flat off-topic tail's tiny\nstd *inflated* the margin — so irrelevant queries scored ``high`` (benchmarked).\n``relative_margin`` is retained for transparency but is NO LONGER the basis for\n``level``; note it reads high even for off-topic queries.\n\n``prominence`` / ``relative_margin`` are None for keyword-only searches (no\nsemantic cosines) and single-candidate pools; there ``level`` falls back to the\noriginal z-score separation heuristic."
    SelectorReport:
      properties:
        applied:
          type: boolean
          title: Applied
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        kept:
          anyOf:
          - type: integer
          - type: 'null'
          title: Kept
        dropped:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dropped
        dropped_memory_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Dropped Memory Ids
        reason:
          anyOf:
          - type: string
            enum:
            - timeout
            - provider_error
            - invalid_answer
            - daily_cap
            - too_large
            - no_provider
            - counter_unavailable
            - inactive
          - type: 'null'
          title: Reason
      type: object
      required:
      - applied
      title: SelectorReport
      description: '#2144: what the recall LLM selector did to this page.


        ``applied: true`` carries ``model``, ``kept`` / ``dropped`` (results left

        and removed) and ``dropped_memory_ids`` (at most 20, page order);

        ``applied: false`` carries only ``reason`` and the page is the unselected

        one. Serialized without the unset keys.'
    MemoryResponse:
      properties:
        memory_id:
          title: Memory Id
        summary:
          title: Summary
        context_summary:
          title: Context Summary
        type:
          title: Type
        importance:
          title: Importance
        scope:
          title: Scope
        created_at:
          title: Created At
        updated_at:
          title: Updated At
        observed_at:
          title: Observed At
        client:
          title: Client
        tags:
          title: Tags
        context:
          title: Context
        score:
          title: Score
          description: 検索スコア（recall時のみ）
        source_uri:
          title: Source Uri
        source_type:
          title: Source Type
        superseded_by:
          title: Superseded By
        contradicts:
          title: Contradicts
        supersede_candidate: {}
        folded: {}
        version:
          title: Version
        content:
          title: Content
        content_truncated:
          title: Content Truncated
        content_next_offset:
          title: Content Next Offset
        spans:
          title: Spans
      type: object
      required:
      - memory_id
      - summary
      - context_summary
      - type
      - importance
      - scope
      - created_at
      - client
      - tags
      - context
      title: MemoryResponse
      description: Response schema for single memory.
    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
    ShareKeyCreateResponse:
      properties:
        id:
          title: Id
          description: Public id of the share key (`skey_` + 22 base62 characters)
        key_prefix:
          title: Key Prefix
          description: First 16 characters of the key (display only)
        name:
          title: Name
          description: Friendly name
        user_id:
          title: User Id
          description: Minting owner
        context_id:
          title: Context Id
          description: The single context this key is confined to
        scope:
          title: Scope
          description: Always 'memory:read'
        created_at:
          title: Created At
          description: Creation timestamp
        last_used_at:
          title: Last Used At
          description: Last usage timestamp
        revoked_at:
          title: Revoked At
          description: Revocation timestamp
        expires_at:
          title: Expires At
          description: Expiry timestamp (always set)
        status:
          title: Status
          description: Current status
        share_key:
          title: Share Key
          description: Plaintext share key (ONLY shown once — must be saved by the client)
      type: object
      required:
      - id
      - key_prefix
      - name
      - user_id
      - context_id
      - scope
      - created_at
      - expires_at
      - status
      - share_key
      title: ShareKeyCreateResponse
      description: Mint response — includes the plaintext key ONCE.
    ShareKeyResponse:
      properties:
        id:
          title: Id
          description: Public id of the share key (`skey_` + 22 base62 characters)
        key_prefix:
          title: Key Prefix
          description: First 16 characters of the key (display only)
        name:
          title: Name
          description: Friendly name
        user_id:
          title: User Id
          description: Minting owner
        context_id:
          title: Context Id
          description: The single context this key is confined to
        scope:
          title: Scope
          description: Always 'memory:read'
        created_at:
          title: Created At
          description: Creation timestamp
        last_used_at:
          title: Last Used At
          description: Last usage timestamp
        revoked_at:
          title: Revoked At
          description: Revocation timestamp
        expires_at:
          title: Expires At
          description: Expiry timestamp (always set)
        status:
          title: Status
          description: Current status
      type: object
      required:
      - id
      - key_prefix
      - name
      - user_id
      - context_id
      - scope
      - created_at
      - expires_at
      - status
      title: ShareKeyResponse
      description: Share-key metadata (never includes the secret).