Kagura AI Resources API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Resources API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: Resources
  description: Resource listing and event-history inspection
paths:
  /api/v1/resources/{resource_id}/events:
    get:
      tags:
      - Resources
      summary: List Resource Events Route
      description: 'Browse ingested events for a resource, newest first (cursor-paginated).


        Owner-only (``WorkspaceOwner``) for parity with the rest of the resources

        surface (#389). Events are scoped to the caller''s workspace via the

        authoritative ``resource_pk``; a slug that does not resolve to a Resource

        in this workspace returns an empty page (CWE-639 fail-safe).


        Example:

        GET /api/v1/resources/ec-products/events?op=upsert&limit=20'
      operationId: list_resource_events_route_api_v1_resources__resource_id__events_get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: op
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - upsert
            - delete
            type: string
          - type: 'null'
          description: Filter by operation type
          title: Op
        description: Filter by operation type
      - name: doc_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by exact document id
          title: Doc Id
        description: Filter by exact document id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by exact document version
          title: Version
        description: Filter by exact document version
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only events created at or after this ISO 8601 timestamp
          title: Since
        description: Only events created at or after this ISO 8601 timestamp
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100
            minimum: 1
          - type: 'null'
          description: Page size (default 20, max 100)
          title: Limit
        description: Page size (default 20, max 100)
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque cursor from a previous response's next_cursor
          title: Cursor
        description: Opaque cursor from a previous response's next_cursor
      - 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/ResourceEventsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/resources:
    get:
      tags:
      - Resources
      summary: List Resources
      description: 'List all resources in the caller''s current workspace.


        Returns an ordered list (latest activity first) of contexts that have a

        non-null ``resource_id``, with aggregated counts joined from the

        resource_tokens, memories, resource_schemas, and resource_events tables.


        #1863: a resource whose contexts were all deleted is still listed, with

        the context fields null, while it has active tokens. Those tokens keep

        authenticating ingest, so the owner needs a way to reach and revoke them;

        once the last one is revoked the row disappears.


        Owner-only (#389): ``WorkspaceOwner`` rejects non-owners with 403.

        ``get_accessible_contexts`` below is a no-op for owners and retained

        as defense-in-depth against a role-gate regression.


        Example:

        GET /api/v1/resources'
      operationId: list_resources_api_v1_resources_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/ResourceListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/resources/{resource_id}/public-mcp:
    post:
      tags:
      - Resources
      summary: Publish Public Mcp Endpoint
      description: 'Publish the resource''s context as an anonymous read-only MCP endpoint.


        Preconditions: the resource exists in the workspace and its live context

        is public (``is_public=true``, not private). One live endpoint per

        context (409 otherwise). The public text is what anonymous clients see;

        nothing falls back to the context''s internal summary or usage guide.'
      operationId: publish_public_mcp_endpoint_api_v1_resources__resource_id__public_mcp_post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Resource slug (`setup_resource`'s resource_id).
          title: Resource Id
        description: Resource slug (`setup_resource`'s resource_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/PublicMcpEndpointCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMcpEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Resources
      summary: Get Public Mcp Endpoint
      description: Return the resource's live public MCP endpoint (404 when none).
      operationId: get_public_mcp_endpoint_api_v1_resources__resource_id__public_mcp_get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Resource slug (`setup_resource`'s resource_id).
          title: Resource Id
        description: Resource slug (`setup_resource`'s resource_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/PublicMcpEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Resources
      summary: Update Public Mcp Endpoint
      description: 'Edit the approved public text; the address stays the same.


        An empty string clears the description or usage guide; the name cannot

        be cleared.'
      operationId: update_public_mcp_endpoint_api_v1_resources__resource_id__public_mcp_patch
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Resource slug (`setup_resource`'s resource_id).
          title: Resource Id
        description: Resource slug (`setup_resource`'s resource_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/PublicMcpEndpointUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMcpEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Resources
      summary: Unpublish Public Mcp Endpoint
      description: 'Unpublish: the address answers 404 from the next request on.'
      operationId: unpublish_public_mcp_endpoint_api_v1_resources__resource_id__public_mcp_delete
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Resource slug (`setup_resource`'s resource_id).
          title: Resource Id
        description: Resource slug (`setup_resource`'s resource_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/resources/{resource_id}/public-mcp/usage-health:
    get:
      tags:
      - Resources
      summary: Get Public Mcp Usage Health
      description: 'Recent usage events of the resource''s public endpoint and recording health.


        Owner-only: ``WorkspaceOwner`` refuses non-owners (403) and

        ``resolve_resource_by_slug(required_role="owner")`` answers 404 for a

        slug of another workspace.'
      operationId: get_public_mcp_usage_health_api_v1_resources__resource_id__public_mcp_usage_health_get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Resource slug (`setup_resource`'s resource_id).
          title: Resource Id
        description: Resource slug (`setup_resource`'s resource_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/PublicMcpUsageHealthResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PublicMcpEndpointCreate:
      properties:
        public_name:
          type: string
          maxLength: 200
          minLength: 1
          title: Public Name
          description: Approved public name
        public_description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Public Description
          description: Approved public description
        public_usage_guide:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Public Usage Guide
          description: Approved public usage guide, returned by get_context_info
      type: object
      required:
      - public_name
      title: PublicMcpEndpointCreate
      description: Approved public text for a new publication.
    PublicMcpEndpointResponse:
      properties:
        public_id:
          title: Public Id
          description: Opaque endpoint id (`pmcp_` + 22 base62)
        endpoint_path:
          title: Endpoint Path
          description: Path of the endpoint on this deployment (`/mcp/public/<public_id>`)
        resource_id:
          title: Resource Id
        context_id:
          title: Context Id
        public_name:
          title: Public Name
        public_description:
          title: Public Description
        public_usage_guide:
          title: Public Usage Guide
        created_at:
          title: Created At
        updated_at:
          title: Updated At
        serving:
          title: Serving
          description: 'Whether the endpoint answers right now: the operator switch MCP_PUBLIC_ENDPOINTS_ENABLED is on and the context is still public and bound to the resource'
      type: object
      required:
      - public_id
      - endpoint_path
      - resource_id
      - context_id
      - public_name
      - created_at
      - serving
      title: PublicMcpEndpointResponse
      description: A live public MCP endpoint of a resource.
    PublicMcpUsageHealthResponse:
      properties:
        resource_id:
          title: Resource Id
        endpoint_id:
          title: Endpoint Id
          description: The live public endpoint's id; null when the resource is not published
        window_hours:
          title: Window Hours
        events:
          title: Events
          description: Events of the live endpoint in the window
        outcomes:
          title: Outcomes
          description: Those events by outcome
        gaps: {}
        writer: {}
        retention_days:
          title: Retention Days
      type: object
      required:
      - resource_id
      - window_hours
      - events
      - outcomes
      - gaps
      - writer
      - retention_days
      title: PublicMcpUsageHealthResponse
      description: Whether usage of the resource's public MCP endpoint is being recorded.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResourceEventsResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ResourceEventRecord'
          type: array
          title: Events
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor for the next page; null on the last page
      type: object
      required:
      - events
      title: ResourceEventsResponse
      description: Cursor-paginated resource events response.
    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
    PublicMcpEndpointUpdate:
      properties:
        public_name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Public Name
        public_description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Public Description
        public_usage_guide:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Public Usage Guide
      type: object
      title: PublicMcpEndpointUpdate
      description: Edit of the approved public text; omitted fields keep their value.
    ResourceListResponse:
      properties:
        resources:
          items:
            $ref: '#/components/schemas/ResourceListItem'
          type: array
          title: Resources
        total:
          type: integer
          title: Total
      type: object
      required:
      - resources
      - total
      title: ResourceListResponse
      description: Workspace resource list response.
    ResourceEventRecord:
      properties:
        id:
          type: string
          title: Id
          description: BigInt append-only event id (also the cursor key), serialized as a string so JS clients can't lose precision above 2^53-1
        op:
          type: string
          title: Op
          description: 'Operation: ''upsert'' or ''delete'''
        doc_id:
          type: string
          title: Doc Id
          description: Document identifier (stable across versions)
        version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
          description: Document version; null for delete-all-versions
        idempotency_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency Key
          description: Client-provided deduplication key, if any
        importance:
          type: number
          title: Importance
          description: Importance score (0.0–1.0)
        created_at:
          type: string
          title: Created At
          description: Event creation time (ISO 8601 UTC)
        payload:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Payload
          description: JSONB payload; null for delete ops OR when omitted because it exceeds the inline size cap (see payload_truncated)
        event_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Event Metadata
          description: Additional metadata (source, correlation_id, etc.)
        payload_bytes:
          type: integer
          title: Payload Bytes
          description: Serialized payload size in bytes (0 when null)
        payload_truncated:
          type: boolean
          title: Payload Truncated
          description: True when the payload exceeded the inline size cap and was omitted from this response
      type: object
      required:
      - id
      - op
      - doc_id
      - importance
      - created_at
      - payload_bytes
      - payload_truncated
      title: ResourceEventRecord
      description: A single ingest event row for the Resource Detail Data tab.
    ResourceListItem:
      properties:
        resource_id:
          type: string
          title: Resource Id
          description: Resource identifier
        context_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Id
          description: 'UUID of the context bound to this resource. Null when every context of the resource has been deleted (#1863): such a row is listed only while the resource still has active tokens, so they stay reachable.'
        context_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Name
          description: Context name (URL-safe identifier)
        context_display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Display Name
          description: Human-readable context name
        token_count:
          type: integer
          title: Token Count
          description: Number of active resource tokens
        memory_count:
          type: integer
          title: Memory Count
          description: Number of non-deleted memories
        current_schema_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Schema Version
          description: Latest schema version, or null if no schema registered
        created_at:
          type: string
          title: Created At
          description: Context creation time (ISO 8601 UTC)
        updated_at:
          type: string
          title: Updated At
          description: Most recent activity — GREATEST(last_event_at, context.updated_at, context.created_at) as ISO 8601 UTC
      type: object
      required:
      - resource_id
      - token_count
      - memory_count
      - created_at
      - updated_at
      title: ResourceListItem
      description: Single resource entry in the workspace resource list.