---
title: "Create Schema"
method: POST
path: "/api/v1/resources/{resource_id}/schema"
tags: ["resource-schema"]
---

# Create Schema

`POST /api/v1/resources/{resource_id}/schema`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/resources/{resource_id}/schema`
- Auth: none declared

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"
            }
        ]
    }

## Path parameters

- `resource_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- SchemaCreateRequest: Request to create a new resource schema.
  - `resource_id` string, required: Resource identifier
  - `field_definitions` FieldDefinition[], required: Field metadata (max 100 fields)
    - `name` string, required: Field name in JSONB payload
    - `type` string, required: Field data type
    - `description` string, required: Human-readable description
    - `classification` string: Data classification for access control
    - `index_hint` string: Indexing hints: fulltext, vector, sort, facet, metadata
    - `unit` string, nullable: Unit of measurement (e.g., JPY, kg)
    - `enum_values` string[], nullable: Allowed values for categorical fields
    - `example` string, nullable: Example value
    - `required` boolean: Whether field is required

## Response `201`

Successful Response

- SchemaResponse: Response with resource schema.
  - `resource_id` string, required
  - `schema_version` integer, required
  - `field_definitions` FieldDefinition[], required
    - `name` string, required: Field name in JSONB payload
    - `type` string, required: Field data type
    - `description` string, required: Human-readable description
    - `classification` string: Data classification for access control
    - `index_hint` string: Indexing hints: fulltext, vector, sort, facet, metadata
    - `unit` string, nullable: Unit of measurement (e.g., JPY, kg)
    - `enum_values` string[], nullable: Allowed values for categorical fields
    - `example` string, nullable: Example value
    - `required` boolean: Whether field is required
  - `created_at` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)