Schema Management

Create User Schema V1

Create a new user-defined graph schema.

This endpoint allows users to define custom node types and relationships for their knowledge graph.
The schema will be validated and stored for use in future memory extractions.

**Features:**
- Define custom node types with properties and validation rules
- Define custom relationship types with constraints
- Automatic validation against system schemas
- Support for different scopes (personal, workspace, namespace, organization)
- **Status control**: Set `status` to "active" to immediately activate the schema, or "draft" to save as draft (default)
- **Enum support**: Use `enum_values` to restrict property values to a predefined list (max 15 values)
- **Auto-indexing**: Required properties are automatically indexed in Neo4j when schema becomes active

**Schema Limits (optimized for LLM performance):**
- **Maximum 10 node types** per schema
- **Maximum 20 relationship types** per schema
- **Maximum 10 properties** per node type
- **Maximum 15 enum values** per property

**Property Types & Validation:**
- `string`: Text values with optional `enum_values`, `min_length`, `max_length`, `pattern`
- `integer`: Whole numbers with optional `min_value`, `max_value`
- `float`: Decimal numbers with optional `min_value`, `max_value`
- `boolean`: True/false values
- `datetime`: ISO 8601 timestamp strings
- `array`: Lists of values
- `object`: Complex nested objects

**Enum Values:**
- Add `enum_values` to any string property to restrict values to a predefined list
- Maximum 15 enum values allowed per property
- Use with `default` to set a default enum value
- Example: `"enum_values": ["small", "medium", "large"]`

**When to Use Enums:**
- Limited, well-defined options (≤15 values): sizes, statuses, categories, priorities
- Controlled vocabularies: "active/inactive", "high/medium/low", "bronze/silver/gold"
- When you want exact matching and no variations

**When to Avoid Enums:**
- Open-ended text fields: names, titles, descriptions, addresses
- Large sets of options (>15): countries, cities, product models
- When you want semantic similarity matching for entity resolution
- Dynamic or frequently changing value sets

**Unique Identifiers & Entity Resolution:**
- Properties marked as `unique_identifiers` are used for entity deduplication and merging
- **With enum_values**: Exact matching is used - entities with the same enum value are considered identical
- **Without enum_values**: Semantic similarity matching is used - entities with similar meanings are automatically merged
- Example: A "name" unique_identifier without enums will merge "Apple Inc" and "Apple Inc." as the same entity
- Example: A "sku" unique_identifier with enums will only merge entities with exactly matching SKU codes
- Use enums for unique_identifiers when you have a limited, predefined set of values (≤15 options)
- Avoid enums for unique_identifiers when you have broad, open-ended values or >15 possible options
- **Best practices**: Use enums for controlled vocabularies (status codes, categories), avoid for open text (company names, product titles)
- **In the example above**: "name" uses semantic similarity (open-ended), "sku" uses exact matching (controlled set)

**LLM-Friendly Descriptions:**
- Write detailed property descriptions that guide the LLM on expected formats and usage
- Include examples of typical values (e.g., "Product name, typically 2-4 words like 'iPhone 15 Pro'")
- Specify data formats and constraints clearly (e.g., "Price in USD as decimal number")
- For enums, explain when to use each option (e.g., "use 'new' for brand new items")

**Authentication Required**:
One of the following authentication methods must be used:
- Bearer token in `Authorization` header
- API Key in `X-API-Key` header
- Session token in `X-Session-Token` header

**Required Headers**:
- Content-Type: application/json
- X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')

post/v1/schemas

Request body

idstring

namestring required

descriptionstring nullable

versionstring

organization_idstring nullable

Organization ID this schema belongs to. Accepts legacy 'organization' alias.

namespace_idstring nullable

Namespace ID this schema belongs to. Accepts legacy 'namespace' alias.

node_typesobject

Custom node types (max 10 per schema)

relationship_typesobject

Custom relationship types (max 20 per schema)

memory_policyobject nullable

Default memory policy for memories using this schema. Includes mode ('auto', 'manual'), node_constraints (applied in auto mode when present), and OMO safety settings (consent, risk). Memory-level policies override schema-level.

status'draft' | 'active' | 'deprecated' | 'archived'

scope'personal' | 'workspace' | 'namespace' | 'organization'

Schema scopes available through the API

created_atstring date-time

updated_atstring date-time nullable

read_accessstring[]

write_accessstring[]

usage_countinteger

last_used_atstring date-time nullable

Response

Successful Response

successboolean required

errorstring nullable

codeinteger

Changes

Changed in 4 of the 37 revisions of this API.11100

Mar 13, 20260e4854909d2a14See the full diff
- ○
  added the new optional request property ////////
  new-optional-request-property
- ○
  added the new optional request property ////////
  new-optional-request-property
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Feb 7, 20265f5df128dbcd66See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  added the optional property //// to the response with the status
  response-optional-property-added
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/namespace deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/namespace deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/namespace deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/namespace deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/namespace deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/organization deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/organization deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/organization deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/organization deprecated
  response-property-deprecated
- ○
  response property data/anyOf[subschema #1: UserGraphSchema]/organization deprecated
  response-property-deprecated
Nov 19, 20252422ab514a9d1119See the full diff
- ●
  removed the request property
  request-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  added the new namespace enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new namespace enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new namespace enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new namespace enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new namespace enum value to the // response property for the response status
  response-property-enum-value-added
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  the request property default value changed from workspace to organization
  request-property-default-value-changed
- ○
  added the new namespace enum value to the request property
  request-property-enum-value-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  the response's property default value changed from workspace to organization for the status
  response-property-default-value-changed
- ○
  the response's property default value changed from workspace to organization for the status
  response-property-default-value-changed
- ○
  the response's property default value changed from workspace to organization for the status
  response-property-default-value-changed
- ○
  the response's property default value changed from workspace to organization for the status
  response-property-default-value-changed
- ○
  the response's property default value changed from workspace to organization for the status
  response-property-default-value-changed
Nov 7, 202514ff137558711See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 12 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history