Kagura AI Resource Schema API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Resource Schema API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: resource-schema
  description: Resource schema registry
paths:
  /api/v1/resources/{resource_id}/schema:
    get:
      tags:
      - resource-schema
      summary: Get Schema
      description: 'Get resource schema (latest or specific version).


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

        ``resolve_resource_by_slug`` returns 404 on cross-workspace probes.


        Example:

        GET /api/v1/resources/ec_products/schema

        GET /api/v1/resources/ec_products/schema?schema_version=2'
      operationId: get_schema_api_v1_resources__resource_id__schema_get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: schema_version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Schema Version
      - 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/SchemaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - resource-schema
      summary: Create Schema
      description: 'Create a new resource schema version.


        Issue #276: Owner-only access via WorkspaceOwner dependency.


        Args:

        resource_id: Resource identifier

        request: Schema creation request

        owner: Workspace owner (user_id, workspace_id) from dependency

        db: Database session


        Returns:

        Created schema


        Raises:

        403: Not workspace owner

        400: Invalid resource_id or schema definition

        404: No such resource in the caller''s workspace

        409: The resource has no live context (#1877)


        Notes:

        - Automatically increments schema_version

        - Only workspace owners can create schemas

        - Triggers rebuild for all contexts using this resource (TODO: Week 4)


        Example:

        POST /api/v1/resources/ec_products/schema

        Body:

        {

        "resource_id": "ec_products",

        "field_definitions": [

        {

        "name": "product_name",

        "type": "text",

        "description": "商品名",

        "classification": "public",

        "index_hint": "fulltext+vector",

        "required": true

        },

        {

        "name": "price",

        "type": "number",

        "description": "価格（税込）",

        "unit": "JPY",

        "index_hint": "sort+facet"

        }

        ]

        }'
      operationId: create_schema_api_v1_resources__resource_id__schema_post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: 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/SchemaCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/resources/{resource_id}/impact:
    get:
      tags:
      - resource-schema
      summary: Get Resource Impact
      description: 'Get resource change impact information.


        Issue #266: Shows the impact of creating/modifying a schema.

        Owner-only (#389): same two-layer gate as ``get_schema`` —

        ``WorkspaceOwner`` → 403 for non-owners, ``resolve_resource_by_slug`` →

        404 on cross-workspace probes. The prior manual workspace-boundary

        SELECT block was superseded by the helper.


        Example:

        GET /api/v1/resources/ec_products/impact'
      operationId: get_resource_impact_api_v1_resources__resource_id__impact_get
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: 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/ResourceImpactResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SchemaCreateRequest:
      properties:
        resource_id:
          type: string
          maxLength: 255
          minLength: 1
          title: Resource Id
          description: Resource identifier
        field_definitions:
          items:
            $ref: '#/components/schemas/FieldDefinition'
          type: array
          maxItems: 100
          minItems: 1
          title: Field Definitions
          description: Field metadata (max 100 fields)
      type: object
      required:
      - resource_id
      - field_definitions
      title: SchemaCreateRequest
      description: Request to create a new resource schema.
    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
    ResourceImpactResponse:
      properties:
        resource_id:
          type: string
          title: Resource Id
        token_count:
          type: integer
          title: Token Count
          description: Number of active tokens using this resource
        memory_count:
          type: integer
          title: Memory Count
          description: Number of existing memories from this resource
        current_schema_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Schema Version
          description: Current schema version (null if no schema exists)
      type: object
      required:
      - resource_id
      - token_count
      - memory_count
      title: ResourceImpactResponse
      description: 'Response with resource change impact information.


        Issue #266: Schema change impact warnings.'
    FieldDefinition:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Field name in JSONB payload
        type:
          type: string
          pattern: ^(text|number|boolean|date|array|object)$
          title: Type
          description: Field data type
        description:
          type: string
          maxLength: 500
          minLength: 1
          title: Description
          description: Human-readable description
        classification:
          type: string
          pattern: ^(public|internal|pii|confidential)$
          title: Classification
          description: Data classification for access control
          default: public
        index_hint:
          type: string
          maxLength: 100
          title: Index Hint
          description: 'Indexing hints: fulltext, vector, sort, facet, metadata'
          default: ''
        unit:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Unit
          description: Unit of measurement (e.g., JPY, kg)
        enum_values:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enum Values
          description: Allowed values for categorical fields
        example:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Example
          description: Example value
        required:
          type: boolean
          title: Required
          description: Whether field is required
          default: false
      type: object
      required:
      - name
      - type
      - description
      title: FieldDefinition
      description: Field metadata definition.
    SchemaResponse:
      properties:
        resource_id:
          type: string
          title: Resource Id
        schema_version:
          type: integer
          title: Schema Version
        field_definitions:
          items:
            $ref: '#/components/schemas/FieldDefinition'
          type: array
          title: Field Definitions
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - resource_id
      - schema_version
      - field_definitions
      - created_at
      title: SchemaResponse
      description: Response with resource schema.