{ "openapi": "3.1.0", "info": { "title": "Papr Memory API", "description": "API for managing enterprise context and memory items with authentication and user-specific data.\n## Authentication\nThis API supports three authentication methods:\n- **API Key**: Include your API key in the `X-API-Key` header\n ```\n X-API-Key: \n ```\n- **Session Token**: Include your session token in the `X-Session-Token` header\n ```\n X-Session-Token: \n ```\n- **Bearer Token**: Include your OAuth2 token from Auth0 in the `Authorization` header\n ```\n Authorization: Bearer \n ```\nAll endpoints require one of these authentication methods.", "version": "1.0.0" }, "paths": { "/v1/memory": { "post": { "tags": [ "v1", "Memory" ], "summary": "Add Memory V1", "description": "Add a new memory item to the system with size validation and background processing.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')\n \n **Role-Based Memory Categories**:\n - **User memories**: preference, task, goal, facts, context\n - **Assistant memories**: skills, learning\n \n **New Metadata Fields**:\n - `metadata.role`: Optional field to specify who generated the memory (user or assistant)\n - `metadata.category`: Optional field for memory categorization based on role\n - Both fields are stored within metadata at the same level as topics, location, etc.\n \n The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).", "operationId": "add_memory", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "skip_background_processing", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If True, skips adding background tasks for processing", "default": false, "title": "Skip Background Processing" }, "description": "If True, skips adding background tasks for processing" }, { "name": "format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Response format. Use 'omo' for Open Memory Object standard format (portable across platforms).", "title": "Format" }, "description": "Response format. Use 'omo' for Open Memory Object standard format (portable across platforms)." }, { "name": "webhook_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}.", "title": "Webhook Url" }, "description": "Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}." }, { "name": "webhook_secret", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature.", "title": "Webhook Secret" }, "description": "Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMemoryRequest" } } } }, "responses": { "200": { "description": "Memory successfully added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMemoryResponse" }, "example": { "code": 200, "status": "success", "data": [ { "id": "mem_123", "content": "Sample memory content.", "type": "text", "metadata": { "topics": "example, memory", "role": "user", "category": "task" }, "createdAt": "2024-06-01T12:00:00Z" } ] } } } }, "207": { "description": "Memory added with degraded functionality", "content": { "application/json": { "example": { "code": 207, "status": "success", "data": [ { "id": "mem_124", "content": "Sample memory content.", "type": "text", "metadata": { "topics": "example, memory" }, "createdAt": "2024-06-01T12:01:00Z" } ], "details": { "warning": "Neo4j unavailable, stored in Pinecone only." } }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "code": 400, "status": "error", "error": "Invalid request payload.", "details": { "field": "content", "reason": "Missing required field." } }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "code": 401, "status": "error", "error": "Missing or invalid authentication." }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "403": { "description": "Subscription limit reached", "content": { "application/json": { "example": { "code": 403, "status": "error", "error": "Subscription limit reached. Upgrade required.", "details": { "limit": "memory quota" } }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "413": { "description": "Content too large", "content": { "application/json": { "example": { "code": 413, "status": "error", "error": "Content size (16000 bytes) exceeds maximum limit of 15000 bytes.", "details": { "max_content_length": 15000 } }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "example": { "code": 415, "status": "error", "error": "Unsupported media type. Use application/json." }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "code": 500, "status": "error", "error": "Internal server error.", "details": { "trace_id": "abc123" } }, "schema": { "$ref": "#/components/schemas/AddMemoryResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/memory/status/{memory_id}": { "get": { "tags": [ "v1", "Memory", "Memory Status" ], "summary": "Get Memory Status", "description": "Get processing status for a memory item.\n\n Returns the current processing lifecycle stage:\n - `queued` — Accepted, waiting to be processed\n - `quick_saved` — Quick add complete (stored in DB + vector store), background processing pending\n - `processing` — Background processing in progress (graph indexing, Neo4j nodes, enrichment)\n - `completed` — All processing finished\n - `failed` — Processing failed\n\n Use this endpoint to poll for completion after adding a memory.\n For real-time updates, connect to WebSocket at `/ws/memory-status/{memory_id}`.", "operationId": "get_memory_status_v1_memory_status__memory_id__get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } } ], "responses": { "200": { "description": "Memory processing status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Memory Status V1 Memory Status Memory Id Get" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Memory not found in processing tracker" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/memory/batch/status/{batch_id}": { "get": { "tags": [ "v1", "Memory", "Memory Status" ], "summary": "Get Batch Memory Status", "description": "Get processing status for a batch of memories.\n\n Returns overall batch progress and per-memory status breakdown.\n The `batch_id` is returned in the POST /v1/memory/batch response.\n\n For real-time updates, connect to WebSocket at `/ws/memory-status`.", "operationId": "get_batch_memory_status_v1_memory_batch_status__batch_id__get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Batch processing status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Batch Memory Status V1 Memory Batch Status Batch Id Get" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Batch not found in processing tracker" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/memory/{memory_id}": { "put": { "tags": [ "v1", "Memory" ], "summary": "Update Memory V1", "description": "Update an existing memory item by ID.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')\n \n The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).", "operationId": "update_memory", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } }, { "name": "enable_holographic", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If True, re-processes holographic neural transforms after content update", "default": false, "title": "Enable Holographic" }, "description": "If True, re-processes holographic neural transforms after content update" }, { "name": "frequency_schema_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact').", "title": "Frequency Schema Id" }, "description": "Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact')." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryRequest" } } } }, "responses": { "200": { "description": "Memory successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } }, "413": { "description": "Content too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryResponse" } } } } }, "x-openai-isConsequential": true }, "delete": { "tags": [ "v1", "Memory" ], "summary": "Delete Memory V1", "description": "Delete a memory item by ID.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "delete_memory", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } }, { "name": "skip_parse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip Parse Server deletion", "default": false, "title": "Skip Parse" }, "description": "Skip Parse Server deletion" } ], "responses": { "200": { "description": "Memory successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } }, "207": { "description": "Partially successful deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponse" } } } } }, "x-openai-isConsequential": true }, "get": { "tags": [ "v1", "Memory" ], "summary": "Get Memory V1", "description": "Retrieve a memory item by ID.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "get_memory", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } }, { "name": "require_consent", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, return 404 if the memory has consent='none'. Ensures only consented memories are returned.", "default": false, "title": "Require Consent" }, "description": "If true, return 404 if the memory has consent='none'. Ensures only consented memories are returned." }, { "name": "exclude_flagged", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, return 404 if the memory has risk='flagged'. Filters out flagged content.", "default": false, "title": "Exclude Flagged" }, "description": "If true, return 404 if the memory has risk='flagged'. Filters out flagged content." }, { "name": "max_risk", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Maximum risk level allowed. Values: 'none', 'sensitive', 'flagged'. If memory exceeds this, return 404.", "title": "Max Risk" }, "description": "Maximum risk level allowed. Values: 'none', 'sensitive', 'flagged'. If memory exceeds this, return 404." } ], "responses": { "200": { "description": "Memory successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/memory/batch": { "post": { "tags": [ "v1", "Memory" ], "summary": "Add Memory Batch V1", "description": "Add multiple memory items in a batch with size validation and background processing.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')\n \n The API validates individual memory content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).", "operationId": "add_memory_batch", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "skip_background_processing", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If True, skips adding background tasks for processing", "default": false, "title": "Skip Background Processing" }, "description": "If True, skips adding background tasks for processing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryRequest" } } } }, "responses": { "200": { "description": "Memories successfully added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "207": { "description": "Partial success - some memories failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "403": { "description": "Subscription limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "413": { "description": "Content too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/memory/all": { "delete": { "tags": [ "v1", "Memory" ], "summary": "Delete All Memories V1", "description": "Delete all memory items for a user.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **User Resolution**:\n - If only API key is provided: deletes memories for the developer\n - If user_id or external_user_id is provided: resolves and deletes memories for that user\n - Uses the same user resolution logic as other endpoints\n \n **Required Headers**:\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')\n \n **WARNING**: This operation cannot be undone. All memories for the resolved user will be permanently deleted.", "operationId": "delete_all_memories", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional user ID to delete memories for (if not provided, uses authenticated user)", "title": "User Id" }, "description": "Optional user ID to delete memories for (if not provided, uses authenticated user)" }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional external user ID to resolve and delete memories for", "title": "External User Id" }, "description": "Optional external user ID to resolve and delete memories for" }, { "name": "namespace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional namespace ID to scope deletion to", "title": "Namespace Id" }, "description": "Optional namespace ID to scope deletion to" }, { "name": "skip_parse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip Parse Server deletion", "default": false, "title": "Skip Parse" }, "description": "Skip Parse Server deletion" } ], "responses": { "200": { "description": "All memories successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "207": { "description": "Partial success - some memories failed to delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "404": { "description": "No memories found for user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } } } }, "x-openai-isConsequential": true } }, "/v1/memory/search": { "post": { "tags": [ "v1", "Memory" ], "summary": "Search V1", "description": "Search through memories with authentication required.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Response Format Options**:\n Choose between standard JSON or TOON (Token-Oriented Object Notation) format:\n - **JSON (default)**: Standard JSON response format\n - **TOON**: Optimized format achieving 30-60% token reduction for LLM contexts\n - Use `response_format=toon` query parameter\n - Returns `text/plain` with TOON-formatted content\n - Ideal for LLM integrations to reduce API costs and latency\n - Maintains semantic clarity while minimizing token usage\n - Example: `/v1/memory/search?response_format=toon`\n \n **Custom Schema Support**:\n This endpoint supports both system-defined and custom user-defined node types:\n - **System nodes**: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code\n - **Custom nodes**: Defined by developers via UserGraphSchema (e.g., Developer, Product, Customer, Function)\n \n When custom schema nodes are returned:\n - Each custom node includes a `schema_id` field referencing the UserGraphSchema\n - The response includes a `schemas_used` array listing all schema IDs used\n - Use `GET /v1/schemas/{schema_id}` to retrieve full schema definitions including:\n - Node type definitions and properties\n - Relationship type definitions and constraints\n - Validation rules and requirements\n \n **Recommended Headers**:\n ```\n Accept-Encoding: gzip\n ```\n \n The API supports response compression for improved performance. Responses larger than 1KB will be automatically compressed when this header is present.\n \n **HIGHLY RECOMMENDED SETTINGS FOR BEST RESULTS:**\n - Set `enable_agentic_graph: true` for intelligent, context-aware search that can understand ambiguous references\n - Use `max_memories: 15-20` for comprehensive memory coverage\n - Use `max_nodes: 10-15` for comprehensive graph entity relationships\n - Use `response_format: toon` when integrating with LLMs to reduce token costs by 30-60%\n \n **Agentic Graph Benefits:**\n When enabled, the system can understand vague references by first identifying specific entities from your memory graph, then performing targeted searches. For example:\n - \"customer feedback\" → identifies your customers first, then finds their specific feedback\n - \"project issues\" → identifies your projects first, then finds related issues\n - \"team meeting notes\" → identifies your team members first, then finds meeting notes\n - \"code functions\" → identifies your functions first, then finds related code\n \n **Role-Based Memory Filtering:**\n Filter memories by role and category using metadata fields:\n - `metadata.role`: Filter by \"user\" or \"assistant\" \n - `metadata.category`: Filter by category (user: preference, task, goal, facts, context | assistant: skills, learning)\n \n **User Resolution Precedence:**\n - If both user_id and external_user_id are provided, user_id takes precedence.\n - If only external_user_id is provided, it will be resolved to the internal user.\n - If neither is provided, the authenticated user is used.", "operationId": "search_memory", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "max_memories", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 10, "description": "HIGHLY RECOMMENDED: Maximum number of memories to return. Use at least 15-20 for comprehensive results. Lower values (5-10) may miss relevant information. Default is 20 for optimal coverage.", "default": 20, "title": "Max Memories" }, "description": "HIGHLY RECOMMENDED: Maximum number of memories to return. Use at least 15-20 for comprehensive results. Lower values (5-10) may miss relevant information. Default is 20 for optimal coverage." }, { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 10, "description": "HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at least 10-15 for comprehensive graph results. Lower values may miss important entity relationships. Default is 15 for optimal coverage.", "default": 15, "title": "Max Nodes" }, "description": "HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at least 10-15 for comprehensive graph results. Lower values may miss important entity relationships. Default is 15 for optimal coverage." }, { "name": "response_format", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ResponseFormat", "description": "Response format: 'json' (default) or 'toon' (Token-Oriented Object Notation for 30-60% token reduction in LLM contexts)", "default": "json" }, "description": "Response format: 'json' (default) or 'toon' (Token-Oriented Object Notation for 30-60% token reduction in LLM contexts)" }, { "name": "Accept-Encoding", "in": "header", "description": "Recommended to use 'gzip' for response compression", "schema": { "type": "string", "default": "gzip" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successfully retrieved memories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "system_nodes_response": { "summary": "Response with system nodes only", "description": "Standard response when only system-defined node types are found", "value": { "code": 200, "status": "success", "data": { "memories": [ { "id": "mem-123", "content": "John Doe completed the quarterly report", "created_at": "2024-01-15T10:30:00Z" } ], "nodes": [ { "label": "Person", "properties": { "id": "person-123", "name": "John Doe", "role": "Manager" } }, { "label": "Task", "properties": { "id": "task-456", "title": "Quarterly Report", "status": "completed" } } ] }, "search_id": "search-789" } }, "custom_schema_response": { "summary": "Response with custom schema nodes", "description": "Response when custom UserGraphSchema nodes are found", "value": { "code": 200, "status": "success", "data": { "memories": [ { "id": "mem-456", "content": "Rachel Green implemented the validateForm() function", "created_at": "2024-01-15T14:20:00Z" } ], "nodes": [ { "label": "Developer", "properties": { "id": "dev-789", "name": "Rachel Green", "expertise": [ "React", "TypeScript" ], "years_experience": 5 }, "schema_id": "schema_abc123" }, { "label": "Function", "properties": { "id": "func-101", "name": "validateForm", "language": "JavaScript", "description": "Form validation function" }, "schema_id": "schema_abc123" } ], "schemas_used": [ "schema_abc123" ] }, "search_id": "search-101" } }, "mixed_nodes_response": { "summary": "Response with both system and custom nodes", "description": "Response containing both system nodes and custom schema nodes", "value": { "code": 200, "status": "success", "data": { "memories": [ { "id": "mem-789", "content": "Product launch meeting with development team", "created_at": "2024-01-15T16:00:00Z" } ], "nodes": [ { "label": "Meeting", "properties": { "id": "meeting-123", "title": "Product Launch Meeting", "date": "2024-01-15T16:00:00Z" } }, { "label": "Product", "properties": { "id": "prod-456", "name": "Mobile App v2.0", "category": "Software", "price": 29.99 }, "schema_id": "schema_ecommerce_456" } ], "schemas_used": [ "schema_ecommerce_456" ] }, "search_id": "search-202" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "403": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "404": { "description": "No relevant items found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/user": { "post": { "tags": [ "v1", "User" ], "summary": "Create User", "description": "Create a new user or link existing user to developer", "operationId": "create_user", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "create_user", "x-operation-description": "Create a new user or link existing user to developer", "x-operation-tags": [ "User" ] }, "get": { "tags": [ "v1", "User" ], "summary": "List Users", "description": "List users for a developer", "operationId": "list_users", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Page Size" } }, { "name": "external_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id" } }, { "name": "email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "list_users", "x-operation-description": "List users for a developer", "x-operation-tags": [ "User" ] } }, "/v1/user/{user_id}": { "get": { "tags": [ "v1", "User" ], "summary": "Get User", "description": "Get user details by user_id (_User.objectId) and developer association", "operationId": "get_user", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "get_user", "x-operation-description": "Get user details by user_id (_User.objectId) and developer association", "x-operation-tags": [ "User" ] }, "put": { "tags": [ "v1", "User" ], "summary": "Update User", "description": "Update user details by user_id (_User.objectId) and developer association", "operationId": "update_user", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "update_user", "x-operation-description": "Update user details by user_id (_User.objectId) and developer association", "x-operation-tags": [ "User" ] }, "delete": { "tags": [ "v1", "User" ], "summary": "Delete User", "description": "Delete user association with developer and the user itself by , assume external user_id is provided, and resolve to internal user_id (_User.objectId)", "operationId": "delete_user", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "is_external", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Is this an external user ID?", "default": false, "title": "Is External" }, "description": "Is this an external user ID?" }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "delete_user", "x-operation-description": "Delete user association with developer and the user itself by , assume external user_id is provided, and resolve to internal user_id (_User.objectId)", "x-operation-tags": [ "User" ] } }, "/v1/user/batch": { "post": { "tags": [ "v1", "User" ], "summary": "Create User Batch", "description": "Create multiple users or link existing users to developer, and add each to the developer's workspace (if one exists).", "operationId": "create_user_batch", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUserCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-operation-name": "create_user_batch", "x-operation-description": "Create multiple users or link existing users to developer, and add each to the developer's workspace (if one exists).", "x-operation-tags": [ "User" ] } }, "/v1/feedback": { "post": { "tags": [ "v1", "Feedback" ], "summary": "Submit Feedback V1", "description": "Submit feedback on search results to help improve model performance.\n \n This endpoint allows developers to provide feedback on:\n - Overall answer quality (thumbs up/down, ratings)\n - Specific memory relevance and accuracy\n - User engagement signals (copy, save, create document actions)\n - Corrections and improvements\n \n The feedback is used to train and improve:\n - Router model tier predictions\n - Memory retrieval ranking\n - Answer generation quality\n - Agentic graph search performance\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "submit_feedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "200": { "description": "Feedback submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 200, "status": "success", "feedback_id": "fb_123456789", "message": "Feedback submitted successfully and will be processed for model improvement" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 400, "status": "error", "message": "Failed to submit feedback", "error": "Invalid search_id or feedback data", "details": { "field": "search_id", "reason": "Search ID not found" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 401, "status": "error", "message": "Failed to submit feedback", "error": "Missing or invalid authentication" } } } }, "404": { "description": "Search ID not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 404, "status": "error", "message": "Failed to submit feedback", "error": "Search ID abc123def456 not found or access denied" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 500, "status": "error", "message": "Failed to submit feedback", "error": "Internal server error", "details": { "trace_id": "abc123" } } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "x-openai-isConsequential": false } }, "/v1/feedback/batch": { "post": { "tags": [ "v1", "Feedback" ], "summary": "Submit Batch Feedback V1", "description": "Submit multiple feedback items in a single request.\n \n Useful for submitting session-end feedback or bulk feedback collection.\n Each feedback item is processed independently, so partial success is possible.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "submit_batch_feedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch feedback processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackResponse" }, "example": { "code": 200, "status": "success", "feedback_ids": [ "fb_123", "fb_456" ], "successful_count": 2, "failed_count": 0, "errors": [], "message": "Processed 2 feedback items successfully" } } } }, "207": { "description": "Partial success - some feedback items failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackResponse" }, "example": { "code": 207, "status": "success", "feedback_ids": [ "fb_123" ], "successful_count": 1, "failed_count": 1, "errors": [ { "index": 1, "search_id": "abc123", "error": "Search ID not found" } ], "message": "Processed 1 feedback items successfully" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackResponse" }, "example": { "code": 400, "status": "error", "feedback_ids": [], "successful_count": 0, "failed_count": 2, "errors": [ { "index": 0, "search_id": "abc123", "error": "Invalid feedback data" } ], "message": "Batch feedback processed" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackResponse" }, "example": { "code": 401, "status": "error", "feedback_ids": [], "successful_count": 0, "failed_count": 0, "errors": [], "message": "Failed to process batch feedback", "error": "Missing or invalid authentication" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFeedbackResponse" }, "example": { "code": 500, "status": "error", "feedback_ids": [], "successful_count": 0, "failed_count": 0, "errors": [], "message": "Failed to process batch feedback", "error": "Internal server error" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "x-openai-isConsequential": false } }, "/v1/feedback/{feedback_id}": { "get": { "tags": [ "v1", "Feedback" ], "summary": "Get Feedback By Id V1", "description": "Retrieve feedback by ID.\n \n This endpoint allows developers to fetch feedback details by feedback ID.\n Only the user who created the feedback or users with appropriate permissions can access it.\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "get_feedback_by_id", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Feedback retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" }, "example": { "code": 200, "status": "success", "feedback_id": "fb_123456789", "message": "Feedback retrieved successfully", "details": { "feedback_type": "thumbs_up", "feedback_score": 1, "feedback_text": "This was helpful!", "search_id": "search_123", "created_at": "2024-01-17T17:30:45.123456Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "code": 401, "status": "error", "message": "Failed to retrieve feedback", "error": "Missing or invalid authentication" }, "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "404": { "description": "Feedback not found", "content": { "application/json": { "example": { "code": 404, "status": "error", "message": "Failed to retrieve feedback", "error": "Feedback ID fb_123456789 not found or access denied" }, "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "code": 500, "status": "error", "message": "Failed to retrieve feedback", "error": "Internal server error", "details": { "trace_id": "abc123" } }, "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/schemas": { "post": { "tags": [ "v1", "Schema Management" ], "summary": "Create User Schema V1", "description": "Create a new user-defined graph schema.\n \n This endpoint allows users to define custom node types and relationships for their knowledge graph.\n The schema will be validated and stored for use in future memory extractions.\n \n **Features:**\n - Define custom node types with properties and validation rules\n - Define custom relationship types with constraints\n - Automatic validation against system schemas\n - Support for different scopes (personal, workspace, namespace, organization)\n - **Status control**: Set `status` to \"active\" to immediately activate the schema, or \"draft\" to save as draft (default)\n - **Enum support**: Use `enum_values` to restrict property values to a predefined list (max 15 values)\n - **Auto-indexing**: Required properties are automatically indexed in Neo4j when schema becomes active\n \n **Schema Limits (optimized for LLM performance):**\n - **Maximum 10 node types** per schema\n - **Maximum 20 relationship types** per schema\n - **Maximum 10 properties** per node type\n - **Maximum 15 enum values** per property\n \n **Property Types & Validation:**\n - `string`: Text values with optional `enum_values`, `min_length`, `max_length`, `pattern`\n - `integer`: Whole numbers with optional `min_value`, `max_value`\n - `float`: Decimal numbers with optional `min_value`, `max_value`\n - `boolean`: True/false values\n - `datetime`: ISO 8601 timestamp strings\n - `array`: Lists of values\n - `object`: Complex nested objects\n \n **Enum Values:**\n - Add `enum_values` to any string property to restrict values to a predefined list\n - Maximum 15 enum values allowed per property\n - Use with `default` to set a default enum value\n - Example: `\"enum_values\": [\"small\", \"medium\", \"large\"]`\n \n **When to Use Enums:**\n - Limited, well-defined options (≤15 values): sizes, statuses, categories, priorities\n - Controlled vocabularies: \"active/inactive\", \"high/medium/low\", \"bronze/silver/gold\"\n - When you want exact matching and no variations\n \n **When to Avoid Enums:**\n - Open-ended text fields: names, titles, descriptions, addresses\n - Large sets of options (>15): countries, cities, product models\n - When you want semantic similarity matching for entity resolution\n - Dynamic or frequently changing value sets\n \n **Unique Identifiers & Entity Resolution:**\n - Properties marked as `unique_identifiers` are used for entity deduplication and merging\n - **With enum_values**: Exact matching is used - entities with the same enum value are considered identical\n - **Without enum_values**: Semantic similarity matching is used - entities with similar meanings are automatically merged\n - Example: A \"name\" unique_identifier without enums will merge \"Apple Inc\" and \"Apple Inc.\" as the same entity\n - Example: A \"sku\" unique_identifier with enums will only merge entities with exactly matching SKU codes\n - Use enums for unique_identifiers when you have a limited, predefined set of values (≤15 options)\n - Avoid enums for unique_identifiers when you have broad, open-ended values or >15 possible options\n - **Best practices**: Use enums for controlled vocabularies (status codes, categories), avoid for open text (company names, product titles)\n - **In the example above**: \"name\" uses semantic similarity (open-ended), \"sku\" uses exact matching (controlled set)\n \n **LLM-Friendly Descriptions:**\n - Write detailed property descriptions that guide the LLM on expected formats and usage\n - Include examples of typical values (e.g., \"Product name, typically 2-4 words like 'iPhone 15 Pro'\")\n - Specify data formats and constraints clearly (e.g., \"Price in USD as decimal number\")\n - For enums, explain when to use each option (e.g., \"use 'new' for brand new items\")\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n \n **Required Headers**:\n - Content-Type: application/json\n - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')", "operationId": "create_user_schema_v1", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGraphSchema-Input" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "201": { "description": "Schema created successfully", "content": { "application/json": { "example": { "success": true, "data": { "id": "schema_123456789", "name": "E-commerce Schema", "description": "Schema for e-commerce operations", "version": "1.0.0", "status": "active", "node_types": { "Product": { "name": "Product", "label": "Product", "description": "E-commerce product", "properties": { "name": { "type": "string", "required": true, "description": "Product name, typically 2-4 words describing the item (e.g., 'iPhone 15 Pro', 'Nike Running Shoes')" }, "price": { "type": "float", "required": true, "description": "Product price in USD, as a decimal number (e.g., 999.99, 29.95)" }, "category": { "type": "string", "required": true, "description": "Main product category - choose the most appropriate category for this item", "enum_values": [ "electronics", "clothing", "books", "home", "sports" ] }, "condition": { "type": "string", "required": false, "description": "Physical condition of the product - use 'new' for brand new items, 'like_new' for barely used", "enum_values": [ "new", "like_new", "good", "fair", "poor" ], "default": "new" }, "in_stock": { "type": "boolean", "required": true, "description": "Availability status - true if currently available for purchase, false if out of stock" }, "sku": { "type": "string", "required": true, "description": "Stock keeping unit - exact alphanumeric code for inventory tracking", "enum_values": [ "SKU-001", "SKU-002", "SKU-003", "SKU-004", "SKU-005" ] } }, "required_properties": [ "name", "price", "category", "in_stock", "sku" ], "unique_identifiers": [ "name", "sku" ], "color": "#e74c3c" } }, "relationship_types": { "PURCHASED": { "name": "PURCHASED", "allowed_source_types": [ "Customer" ], "allowed_target_types": [ "Product" ] } } }, "code": 201 }, "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "400": { "description": "Invalid schema definition", "content": { "application/json": { "example": { "success": false, "error": "Node type 'Memory' conflicts with system schema", "code": 400 }, "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "success": false, "error": "Missing or invalid authentication", "code": 401 }, "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "success": false, "error": "Internal server error", "code": 500 }, "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } } }, "x-openai-isConsequential": false }, "get": { "tags": [ "v1", "Schema Management" ], "summary": "List User Schemas V1", "description": "List all schemas accessible to the authenticated user.\n \n Returns schemas that the user owns or has read access to, including:\n - Personal schemas created by the user\n - Workspace schemas shared within the user's workspace (legacy)\n - Namespace schemas shared within the user's namespace\n - Organization schemas available to the user's organization\n \n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header", "operationId": "list_user_schemas_v1", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by workspace ID", "title": "Workspace Id" }, "description": "Filter by workspace ID" }, { "name": "status_filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status (draft, active, deprecated, archived)", "title": "Status Filter" }, "description": "Filter by status (draft, active, deprecated, archived)" } ], "responses": { "200": { "description": "Schemas retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaListResponse" }, "example": { "success": true, "data": [ { "id": "schema_123", "name": "E-commerce Schema", "description": "Schema for e-commerce operations", "status": "active", "created_at": "2024-01-17T17:30:45.123456Z" } ], "code": 200, "total": 1 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaListResponse" } } } } }, "x-openai-isConsequential": false } }, "/v1/schemas/{schema_id}": { "get": { "tags": [ "v1", "Schema Management" ], "summary": "Get User Schema V1", "description": "Get a specific schema by ID.\n \n Returns the complete schema definition including node types, relationship types,\n and metadata. User must have read access to the schema.", "operationId": "get_user_schema_v1", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "responses": { "200": { "description": "Schema retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "404": { "description": "Schema not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } } }, "x-openai-isConsequential": false }, "put": { "tags": [ "v1", "Schema Management" ], "summary": "Update User Schema V1", "description": "Update an existing schema.\n \n Allows modification of schema properties, node types, relationship types, and status.\n User must have write access to the schema. Updates create a new version\n while preserving the existing data.\n \n **Status Management:**\n - Set `status` to \"active\" to activate the schema and trigger Neo4j index creation\n - Set `status` to \"draft\" to deactivate the schema\n - Set `status` to \"archived\" to soft-delete the schema", "operationId": "update_user_schema_v1", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Updates" } } } }, "responses": { "200": { "description": "Schema updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "404": { "description": "Schema not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } } }, "x-openai-isConsequential": false }, "delete": { "tags": [ "v1", "Schema Management" ], "summary": "Delete User Schema V1", "description": "Delete a schema.\n \n Soft deletes the schema by marking it as archived. The schema data and\n associated graph nodes/relationships are preserved for data integrity.\n User must have write access to the schema.", "operationId": "delete_user_schema_v1", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "responses": { "200": { "description": "Schema deleted successfully", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Schema not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } }, "x-openai-isConsequential": false } }, "/v1/messages": { "post": { "tags": [ "v1", "Messages" ], "summary": "Store Message", "description": "Store a chat message and queue it for AI analysis and memory creation.\n \n **Authentication Required**: Bearer token, API key, or session token\n \n **Processing Control**:\n - Set `process_messages: true` (default) to enable full AI analysis and memory creation\n - Set `process_messages: false` to store messages only without processing into memories\n \n **Processing Flow** (when process_messages=true):\n 1. Message is immediately stored in PostMessage class\n 2. Background processing analyzes the message for memory-worthiness\n 3. If worthy, creates a memory with appropriate role-based categorization\n 4. Links the message to the created memory\n \n **Role-Based Categories**:\n - **User messages**: preference, task, goal, facts, context\n - **Assistant messages**: skills, learning\n \n **Session Management**:\n - `sessionId` is required to group related messages\n - Use the same `sessionId` for an entire conversation\n - **Optional `title`**: Set a human-readable title for the conversation (e.g., \"Q4 Planning Session\")\n - Retrieve conversation history using GET /messages/sessions/{sessionId}", "operationId": "store_message_v1_messages_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Message stored and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/messages/sessions/{session_id}": { "get": { "tags": [ "v1", "Messages" ], "summary": "Get Session History", "description": "Retrieve message history for a specific conversation session.\n \n **Authentication Required**: Bearer token, API key, or session token\n \n **Pagination**:\n - Use `limit` and `skip` parameters for pagination\n - Messages are returned in **reverse chronological order** (newest first)\n - `total_count` indicates total messages in the session\n \n **Summaries** (if available):\n - Returns hierarchical conversation summaries (short/medium/long-term)\n - Includes `context_for_llm` field with pre-compressed context\n - Summaries are automatically generated every 15 messages\n - Use `/sessions/{session_id}/compress` endpoint to retrieve on-demand\n \n **Access Control**:\n - Only returns messages for the authenticated user\n - Workspace scoping is applied if available", "operationId": "get_session_history_v1_messages_sessions__session_id__get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of messages to return", "default": 50, "title": "Limit" }, "description": "Maximum number of messages to return" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of messages to skip for pagination", "default": 0, "title": "Skip" }, "description": "Number of messages to skip for pagination" } ], "responses": { "200": { "description": "Message history retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageHistoryResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "v1", "Messages" ], "summary": "Update Session", "description": "Update session properties (e.g., title, metadata).\n \n **Authentication Required**: Bearer token, API key, or session token\n \n **Updatable Fields**:\n - `title`: Update the conversation title\n - `metadata`: Update session metadata (merged with existing)\n \n **Example Request**:\n ```json\n {\n \"title\": \"Updated Session Title\",\n \"metadata\": {\"custom_field\": \"value\"}\n }\n ```", "operationId": "update_session_v1_messages_sessions__session_id__patch", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionRequest" } } } }, "responses": { "200": { "description": "Session updated successfully", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/messages/sessions/{session_id}/status": { "get": { "tags": [ "v1", "Messages" ], "summary": "Get Session Status", "description": "Get processing status for messages in a session.\n \n **Authentication Required**: Bearer token, API key, or session token\n \n **Status Information**:\n - Total messages in session\n - Processing status breakdown (queued, analyzing, completed, failed)\n - Any messages with processing errors", "operationId": "get_session_status_v1_messages_sessions__session_id__status_get", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Session processing status", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/messages/sessions/{session_id}/compress": { "get": { "tags": [ "v1", "Messages" ], "summary": "Compress Session", "description": "Get compressed conversation context for a session.\n \n Compress your conversation into hierarchical summaries with rich metadata,\n perfect for reducing token usage in LLM context windows.\n \n **Authentication Required**: Bearer token, API key, or session token\n \n **What it returns**:\n - **short_term**: Last 15 messages compressed\n - **medium_term**: Last ~100 messages compressed \n - **long_term**: Full session compressed\n - **topics**: Key topics discussed\n - **enhanced_fields**: Project context, tech stack, key decisions, next steps, files accessed\n \n **Perfect for**:\n - Reducing token usage in LLM prompts (96% savings)\n - Providing conversation context without full history\n - Quick conversation overview for AI agents\n - Project documentation and status snapshots\n \n **Input**: Just the session ID - all context is extracted automatically", "operationId": "compress_session_v1_messages_sessions__session_id__compress_get", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Session summary (compressed context)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSummaryResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found or no summary exists" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/messages/sessions/{session_id}/process": { "post": { "tags": [ "v1", "Messages" ], "summary": "Process Session Messages", "description": "Process all stored messages in a session that were previously stored with process_messages=false.\n \n **Authentication Required**: Bearer token, API key, or session token\n \n This endpoint allows you to retroactively process messages that were initially stored \n without processing. Useful for:\n - Processing messages after deciding you want them as memories\n - Batch processing large conversation sessions\n - Re-processing sessions with updated AI models\n \n **Processing Behavior**:\n - Only processes messages with status 'stored_only' or 'pending'\n - Uses the same smart batch analysis (every 15 messages)\n - Respects existing memory creation pipeline", "operationId": "process_session_messages_v1_messages_sessions__session_id__process_post", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Session messages queued for processing", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/omo/export": { "post": { "tags": [ "v1", "omo" ], "summary": "Export memories to OMO format", "description": "Export memories in Open Memory Object (OMO) standard format.\n\n This enables memory portability to other OMO-compliant platforms.\n The exported format follows the OMO v1 schema.\n\n **OMO Standard:** https://github.com/papr-ai/open-memory-object", "operationId": "export_memories_omo_v1_omo_export_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OMOExportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OMOExportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/omo/import": { "post": { "tags": [ "v1", "omo" ], "summary": "Import memories from OMO format", "description": "Import memories from Open Memory Object (OMO) standard format.\n\n This enables importing memories from other OMO-compliant platforms.\n\n **OMO Standard:** https://github.com/papr-ai/open-memory-object", "operationId": "import_memories_omo_v1_omo_import_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OMOImportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OMOImportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/omo/export.json": { "get": { "tags": [ "v1", "omo" ], "summary": "Export memories as .omo.json file", "description": "Export memories in OMO JSON file format for download.", "operationId": "export_omo_file_v1_omo_export_json_get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "memory_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of memory IDs", "title": "Memory Ids" }, "description": "Comma-separated list of memory IDs" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/namespace": { "post": { "tags": [ "v1", "Namespace" ], "summary": "Create Namespace", "description": "Create a new namespace within the developer's organization.", "operationId": "create_namespace", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceRequest" } } } }, "responses": { "200": { "description": "Namespace created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } } } }, "get": { "tags": [ "v1", "Namespace" ], "summary": "List Namespaces", "description": "List namespaces for the developer's organization.", "operationId": "list_namespaces", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Skip" }, "description": "Number of items to skip" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max items to return", "default": 20, "title": "Limit" }, "description": "Max items to return" }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Namespaces listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceListResponse" } } } } } } }, "/v1/namespace/{namespace_id}": { "get": { "tags": [ "v1", "Namespace" ], "summary": "Get Namespace", "description": "Retrieve a single namespace by ID.", "operationId": "get_namespace", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Namespace retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } } } }, "put": { "tags": [ "v1", "Namespace" ], "summary": "Update Namespace", "description": "Update an existing namespace.", "operationId": "update_namespace", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNamespaceRequest" } } } }, "responses": { "200": { "description": "Namespace updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceResponse" } } } } } }, "delete": { "tags": [ "v1", "Namespace" ], "summary": "Delete Namespace", "description": "Delete a namespace and optionally cascade-delete all memories, Neo4j nodes, and ACL references associated with it.", "operationId": "delete_namespace", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "delete_memories", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Delete all memories in this namespace", "default": true, "title": "Delete Memories" }, "description": "Delete all memories in this namespace" }, { "name": "delete_neo4j_nodes", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Delete all Neo4j nodes in this namespace", "default": true, "title": "Delete Neo4J Nodes" }, "description": "Delete all Neo4j nodes in this namespace" }, { "name": "remove_acl_references", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Remove namespace from ACL arrays on remaining nodes", "default": true, "title": "Remove Acl References" }, "description": "Remove namespace from ACL arrays on remaining nodes" }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Namespace deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNamespaceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNamespaceResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNamespaceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNamespaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNamespaceResponse" } } } } }, "x-openai-isConsequential": true } }, "/v1/namespace/{namespace_id}/api-keys": { "post": { "tags": [ "v1", "Namespace" ], "summary": "Create Namespace Api Key", "description": "Mint a new API key bound to the given namespace. Caller must authenticate with any API key belonging to the same organization (typically the org-wide / default-namespace key).\n\n**Security:** The full key is returned exactly once in this response. Store it immediately — it cannot be retrieved later. Subsequent reads expose only the masked `key_prefix`.", "operationId": "create_namespace_api_key", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyRequest" } } } }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } }, "404": { "description": "Namespace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceApiKeyResponse" } } } } }, "x-openai-isConsequential": true } }, "/v1/graph/transform": { "post": { "tags": [ "v1", "Graph" ], "summary": "Transform text to graph embeddings", "description": "Vector-store agnostic producer.\n\nReturns everything you'd want to index in any vector DB -- base embedding,\n14-band extracted signals, per-band SBERT/Qwen embeddings, phases, and\noptional rot_v3 / concat reconstructions.\n\nUses the SAME extraction + embedding path as /v1/graph/rerank uses for\nqueries, so artifacts produced here can be scored by /v1/graph/rerank\nwithout any drift.", "operationId": "graph_transform_v1_graph_transform_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphTransformRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphTransformResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/graph/rerank": { "post": { "tags": [ "v1", "Graph" ], "summary": "Rerank documents", "operationId": "graph_rerank_v1_graph_rerank_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRerankRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRerankResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/graph/domains": { "get": { "tags": [ "v1", "Graph Domains" ], "summary": "List domains", "operationId": "list_domains_v1_graph_domains_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainList" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] }, "post": { "tags": [ "v1", "Graph Domains" ], "summary": "Create domain", "operationId": "create_domain_v1_graph_domains_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainSpec" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/graph/domains/{domain_id}": { "get": { "tags": [ "v1", "Graph Domains" ], "summary": "Get domain", "operationId": "get_domain_v1_graph_domains__domain_id__get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainSpec" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "v1", "Graph Domains" ], "summary": "Update domain", "operationId": "update_domain_v1_graph_domains__domain_id__put", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainSpec" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "v1", "Graph Domains" ], "summary": "Delete domain", "operationId": "delete_domain_v1_graph_domains__domain_id__delete", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDomainDelete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/namespace/{namespace_id}/instance": { "put": { "tags": [ "v1", "Instance Configuration" ], "summary": "Set Namespace Instance Config", "description": "Set dedicated instance configuration for a namespace.", "operationId": "set_namespace_instance_config", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "validate", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Test connection before saving", "default": false, "title": "Validate" }, "description": "Test connection before saving" }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "v1", "Instance Configuration" ], "summary": "Get Namespace Instance Config", "description": "Get resolved instance configuration for a namespace (namespace > org). Passwords are masked.", "operationId": "get_namespace_instance_config", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "v1", "Instance Configuration" ], "summary": "Delete Namespace Instance Config", "description": "Remove dedicated instance configuration from a namespace (reverts to org or shared).", "operationId": "delete_namespace_instance_config", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/organization/instance": { "put": { "tags": [ "v1", "Instance Configuration" ], "summary": "Set Organization Instance Config", "description": "Set default dedicated instance configuration for the organization (inherited by namespaces without their own config).", "operationId": "set_organization_instance_config", "parameters": [ { "name": "validate", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Test connection before saving", "default": false, "title": "Validate" }, "description": "Test connection before saving" }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "v1", "Instance Configuration" ], "summary": "Get Organization Instance Config", "description": "Get organization-level instance configuration (masked passwords).", "operationId": "get_organization_instance_config", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "v1", "Instance Configuration" ], "summary": "Delete Organization Instance Config", "description": "Remove organization-level instance configuration (all namespaces revert to shared).", "operationId": "delete_organization_instance_config", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ai/openai/chat/completions": { "post": { "tags": [ "v1", "AI Proxy" ], "summary": "Openai Completions Proxy", "description": "OpenAI Chat Completions API proxy (GPT-4, GPT-4-turbo, etc.)", "operationId": "openai_completions_proxy_v1_ai_openai_chat_completions_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/ai/openai/responses": { "post": { "tags": [ "v1", "AI Proxy" ], "summary": "Openai Responses Proxy", "description": "OpenAI Responses API proxy (GPT-5+, o-series reasoning models)", "operationId": "openai_responses_proxy_v1_ai_openai_responses_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/ai/anthropic/messages": { "post": { "tags": [ "v1", "AI Proxy" ], "summary": "Anthropic Messages Proxy", "description": "Anthropic Messages API proxy (Claude models)", "operationId": "anthropic_messages_proxy_v1_ai_anthropic_messages_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/ai/google/models/{model_id}:generateContent": { "post": { "tags": [ "v1", "AI Proxy" ], "summary": "Google Generate Content Proxy", "description": "Google Gemini generateContent API proxy", "operationId": "google_generate_content_proxy_v1_ai_google_models__model_id__generateContent_post", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ai/google/models/{model_id}:streamGenerateContent": { "post": { "tags": [ "v1", "AI Proxy" ], "summary": "Google Stream Generate Content Proxy", "description": "Google Gemini streamGenerateContent API proxy", "operationId": "google_stream_generate_content_proxy_v1_ai_google_models__model_id__streamGenerateContent_post", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ai/usage": { "get": { "tags": [ "v1", "AI Proxy" ], "summary": "Get Ai Usage", "description": "Get user's AI proxy usage stats and subscription info.", "operationId": "get_ai_usage_v1_ai_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/sync/tiers": { "post": { "tags": [ "v1", "Sync" ], "summary": "Get Sync Tiers", "description": "Return initial Tier 0 (goals/OKRs/use-cases --> tier 0 memories) and Tier 1 (hot memories) for the requesting user/workspace.\n\nThis is a minimal initial implementation to enable SDK integration. It uses simple heuristics and will be enhanced with analytics-driven selection.", "operationId": "get_sync_tiers_v1_sync_tiers_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncTiersRequest" } } }, "required": true }, "responses": { "200": { "description": "Tier assignments returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncTiersResponse" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ] } }, "/v1/sync/delta": { "get": { "tags": [ "v1", "Sync" ], "summary": "Get Sync Delta", "description": "Return upserts/deletes since the provided cursor for a user/workspace.\nCursor is an opaque watermark over updatedAt and objectId.", "operationId": "get_sync_delta_v1_sync_delta_get", "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from previous sync", "title": "Cursor" }, "description": "Opaque cursor from previous sync" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, { "name": "include_embeddings", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Embeddings" } } ], "responses": { "200": { "description": "Delta since cursor returned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Sync Delta V1 Sync Delta Get" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/telemetry/events": { "post": { "tags": [ "v1", "Telemetry" ], "summary": "Telemetry Events", "description": "Telemetry proxy endpoint for anonymous OSS adoption tracking.\n \n This endpoint receives telemetry events from OSS installations and forwards them\n to Amplitude using Papr's API key (which stays secure on the server).\n \n **Privacy**:\n - All user IDs are hashed/anonymized\n - No PII is collected\n - Data is used only for understanding OSS adoption patterns\n \n **Opt-in**: Users must explicitly enable telemetry in their OSS installation.\n \n **Request Body**:\n ```json\n {\n \"events\": [\n {\n \"event_name\": \"memory_created\",\n \"properties\": {\n \"type\": \"text\",\n \"has_metadata\": true\n },\n \"user_id\": \"hashed_user_id\",\n \"timestamp\": 1234567890000\n }\n ],\n \"anonymous_id\": \"session_id\"\n }\n ```", "operationId": "telemetry_events_v1", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-openai-isConsequential": false } }, "/v1/document": { "post": { "tags": [ "v1", "Document" ], "summary": "Upload Document", "description": "Upload and process documents using the pluggable architecture.\n\n **Authentication Required**: Bearer token or API key\n\n **Supported Providers**: TensorLake.ai, Reducto AI, Gemini Vision (fallback)\n\n **Features**:\n - Multi-tenant organization/namespace scoping\n - Temporal workflow for durable execution\n - Real-time WebSocket status updates\n - Integration with Parse Server (Post/PostSocial/PageVersion)\n - Automatic fallback between providers", "operationId": "upload_document_v1_document_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_document_v1_document_post" } } }, "required": true }, "responses": { "200": { "description": "Document upload started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "202": { "description": "Document processing queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } } }, "security": [ { "Bearer": [] }, { "X-API-Key": [] } ] } }, "/v1/document/status/{upload_id}": { "get": { "tags": [ "v1", "Document" ], "summary": "Get Document Status", "description": "Get processing status for an uploaded document", "operationId": "get_document_status_v1_document_status__upload_id__get", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Document Status V1 Document Status Upload Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/document/{upload_id}": { "delete": { "tags": [ "v1", "Document" ], "summary": "Cancel Document Processing", "description": "Cancel document processing", "operationId": "cancel_document_processing_v1_document__upload_id__delete", "security": [ { "Bearer": [] }, { "X-API-Key": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Document Processing V1 Document Upload Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/graphql": { "get": { "tags": [ "v1", "GraphQL" ], "summary": "Graphql Playground", "description": "GraphQL Playground (development only)", "operationId": "graphql_playground_v1_graphql_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "v1", "GraphQL" ], "summary": "Graphql Proxy", "description": "GraphQL endpoint for querying PAPR Memory using GraphQL.\n\n This endpoint proxies GraphQL queries to Neo4j's hosted GraphQL endpoint,\n automatically applying multi-tenant authorization filters based on user_id and workspace_id.\n\n **Authentication Required**:\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header\n - API Key in `X-API-Key` header\n - Session token in `X-Session-Token` header\n\n **Request Body**:\n ```json\n {\n \"query\": \"query { project(id: \\\"proj_123\\\") { name tasks { title } } }\",\n \"variables\": {},\n \"operationName\": \"GetProject\"\n }\n ```\n\n **Example Query**:\n ```graphql\n query GetProjectTasks($projectId: ID!) {\n project(id: $projectId) {\n name\n tasks {\n title\n status\n }\n }\n }\n ```\n\n All queries are automatically filtered by user_id and workspace_id for security.", "operationId": "graphql_query_v1", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "X-API-Key": [] }, { "Bearer": [] } ], "x-openai-isConsequential": false } }, "/login": { "get": { "tags": [ "Authentication" ], "summary": "Login", "description": "OAuth2 login endpoint. Initiates the OAuth2 authorization code flow.\n \n **Query Parameters:**\n - `redirect_uri`: The URI to redirect to after authentication (required)\n - `state`: A random string for CSRF protection (optional but recommended)\n \n **Flow:**\n 1. Client redirects user to this endpoint with `redirect_uri` and `state`\n 2. This endpoint redirects user to Auth0 for authentication\n 3. After authentication, Auth0 redirects to `/callback` with authorization code\n 4. `/callback` redirects back to the original `redirect_uri` with code and state\n \n **Example:**\n ```\n GET /login?redirect_uri=https://chat.openai.com&state=abc123\n ```", "operationId": "oauth2_login", "responses": { "200": { "description": "OAuth2 login initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "description": "Bad request - missing redirect URI", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/callback": { "get": { "tags": [ "Authentication" ], "summary": "Callback", "description": "OAuth2 callback endpoint. Processes the authorization code from Auth0.\n \n **Query Parameters:**\n - `code`: Authorization code from Auth0 (required)\n - `state`: State parameter for CSRF protection (required)\n \n **Flow:**\n 1. Auth0 redirects to this endpoint after successful authentication\n 2. This endpoint validates the authorization code and state\n 3. Redirects back to the original `redirect_uri` with code and state\n 4. Client can then exchange the code for tokens at `/token` endpoint\n \n **Security:**\n - Validates state parameter to prevent CSRF attacks\n - Checks authorization code expiration\n - Cleans up session data after processing", "operationId": "oauth2_callback", "responses": { "200": { "description": "OAuth2 callback processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackResponse" } } } }, "400": { "description": "Bad request - missing code or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/token": { "post": { "tags": [ "Authentication" ], "summary": "Token", "description": "OAuth2 token endpoint. Exchanges authorization code for access tokens.\n \n **Request Body (JSON or Form):**\n - `grant_type`: OAuth2 grant type - \"authorization_code\" or \"refresh_token\" (required)\n - `code`: Authorization code from OAuth2 callback (required for authorization_code grant)\n - `redirect_uri`: Redirect URI used in authorization (required for authorization_code grant)\n - `client_type`: Client type - \"papr_plugin\" or \"browser_extension\" (optional, default: papr_plugin)\n - `refresh_token`: Refresh token for token refresh (required for refresh_token grant)\n \n **Response:**\n - `access_token`: OAuth2 access token for API authentication\n - `token_type`: Token type (Bearer)\n - `expires_in`: Token expiration time in seconds\n - `refresh_token`: Refresh token for getting new access tokens\n - `scope`: OAuth2 scopes granted\n - `user_id`: User ID from Auth0\n \n **Example Request:**\n ```json\n {\n \"grant_type\": \"authorization_code\",\n \"code\": \"abc123...\",\n \"redirect_uri\": \"https://chat.openai.com\",\n \"client_type\": \"papr_plugin\"\n }\n ```", "operationId": "oauth2_token", "responses": { "200": { "description": "OAuth2 token exchange successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Bad request - invalid grant type or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid authorization code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/me": { "get": { "tags": [ "Authentication" ], "summary": "Me", "description": "Get current user information. Validates authentication and returns user details.\n \n **Authentication Required:**\n One of the following authentication methods must be used:\n - Bearer token in `Authorization` header: `Authorization: Bearer `\n - Session token in `Authorization` header: `Authorization: Session `\n - API Key in `Authorization` header: `Authorization: APIKey `\n \n **Headers:**\n - `Authorization`: Authentication token (required)\n - `X-Client-Type`: Client type for logging (optional, default: papr_plugin)\n \n **Response:**\n - `user_id`: Internal user ID\n - `sessionToken`: Session token for API access (if available)\n - `imageUrl`: User profile image URL (if available)\n - `displayName`: User display name (if available)\n - `email`: User email address (if available)\n - `message`: Authentication status message\n \n **Example:**\n ```\n GET /me\n Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\n X-Client-Type: papr_plugin\n ```", "operationId": "get_user_info", "responses": { "200": { "description": "User information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/logout": { "get": { "tags": [ "Authentication" ], "summary": "Logout", "description": "OAuth2 logout endpoint. Logs out the user from Auth0 and redirects to specified URL.\n \n **Query Parameters:**\n - `returnTo`: URL to redirect to after logout (optional, default: extension logout page)\n - `client_type`: Client type for determining Auth0 client ID (optional, default: papr_plugin)\n \n **Flow:**\n 1. Client redirects user to this endpoint\n 2. This endpoint redirects to Auth0 logout URL\n 3. Auth0 logs out the user and redirects to the specified return URL\n \n **Example:**\n ```\n GET /logout?returnTo=https://chat.openai.com\n ```\n \n **Note:** This endpoint initiates the logout process. The actual logout completion happens on Auth0's side.", "operationId": "oauth2_logout", "responses": { "200": { "description": "Logout initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ACLConfig": { "properties": { "read": { "items": { "type": "string" }, "type": "array", "title": "Read", "description": "Entity IDs that can read this memory. Format: 'prefix:id' (e.g., 'external_user:alice', 'organization:org_123'). Supported prefixes: user, external_user, organization, namespace, workspace, role. Unprefixed values treated as external_user for backwards compatibility." }, "write": { "items": { "type": "string" }, "type": "array", "title": "Write", "description": "Entity IDs that can write/modify this memory. Format: 'prefix:id' (e.g., 'external_user:alice'). Supported prefixes: user, external_user, organization, namespace, workspace, role." } }, "additionalProperties": false, "type": "object", "title": "ACLConfig", "description": "Simplified Access Control List configuration.\n\nAligned with Open Memory Object (OMO) standard.\nSee: https://github.com/anthropics/open-memory-object\n\n**Supported Entity Prefixes:**\n\n| Prefix | Description | Validation |\n|--------|-------------|------------|\n| `user:` | Internal Papr user ID | Validated against Parse users |\n| `external_user:` | Your app's user ID | Not validated (your responsibility) |\n| `organization:` | Organization ID | Validated against your organizations |\n| `namespace:` | Namespace ID | Validated against your namespaces |\n| `workspace:` | Workspace ID | Validated against your workspaces |\n| `role:` | Parse role ID | Validated against your roles |\n\n**Examples:**\n```python\nacl = ACLConfig(\n read=[\"external_user:alice_123\", \"organization:org_acme\"],\n write=[\"external_user:alice_123\"]\n)\n```\n\n**Validation Rules:**\n- Internal entities (user, organization, namespace, workspace, role) are validated\n- External entities (external_user) are NOT validated - your app is responsible\n- Invalid internal entities will return an error\n- Unprefixed values default to `external_user:` for backwards compatibility", "examples": [ { "description": "Share with specific user and entire organization", "read": [ "external_user:alice_123", "organization:org_acme" ], "write": [ "external_user:alice_123" ] }, { "description": "Namespace-scoped access", "read": [ "namespace:ns_production", "external_user:admin_bob" ], "write": [ "external_user:admin_bob" ] } ] }, "AddMemoryItem": { "properties": { "memoryId": { "type": "string", "title": "Memoryid" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "objectId": { "type": "string", "title": "Objectid" }, "memoryChunkIds": { "items": { "type": "string" }, "type": "array", "title": "Memorychunkids" } }, "additionalProperties": false, "type": "object", "required": [ "memoryId", "createdAt", "objectId" ], "title": "AddMemoryItem", "description": "Response model for a single memory item in add_memory response" }, "AddMemoryRequest": { "properties": { "policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryAddPolicy" }, { "type": "null" } ], "description": "Unified processing policy: transform_embedding, graph, consent, risk, acl." }, "memory_policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryPolicy" }, { "type": "null" } ], "description": "DEPRECATED: Use 'policy' instead. Legacy graph + OMO policy. Use mode='auto' (LLM extraction, constraints applied if provided) or 'manual' (exact nodes). Includes consent, risk, and ACL settings. If schema_id is set, schema's memory_policy is used as defaults.", "deprecated": true, "x-stainless-deprecation-message": "Use /policy instead." }, "link_to": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Link To", "description": "DEPRECATED: Use policy.graph.link_to instead. Shorthand DSL for node/edge constraints (same as node_constraints, compact syntax). Expands and merges into memory_policy.node_constraints and edge_constraints at resolve time. Default create is upsert; use dict form with create='lookup' (or legacy 'never') for link-only. Formats: - String: 'Task:title' (semantic match on Task.title, upsert by default) - List: ['Task:title', 'Person:email'] (multiple constraints) - Dict: {'Task:title': {'set': {...}, 'create': 'lookup'}} (full options) Syntax: - Node: 'Type:property', 'Type:prop=value' (exact), 'Type:prop~value' (semantic) - Edge: 'Source->EDGE->Target:property' (arrow syntax) - Via: 'Type.via(EDGE->Target:prop)' (relationship traversal) - Special: '$this', '$previous', '$context:N' Example lookup-only: {'SecurityPolicy:name': {'create': 'lookup'}}", "deprecated": true, "x-stainless-deprecation-message": "Use policy.graph.link_to instead." }, "graph_generation": { "anyOf": [ { "$ref": "#/components/schemas/GraphGeneration" }, { "type": "null" } ], "description": "DEPRECATED: Use 'policy.graph' instead. Legacy graph generation configuration. If both policy and graph_generation are provided, policy takes precedence.", "deprecated": true, "x-stainless-deprecation-message": "Use policy.graph instead." }, "content": { "type": "string", "title": "Content", "description": "The content of the memory item you want to add to memory" }, "type": { "$ref": "#/components/schemas/MemoryType", "description": "Memory item type; defaults to 'text' if omitted", "default": "text" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.", "deprecated": true, "x-stainless-deprecation-message": "DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace." }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Your application's user identifier. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email). Papr will automatically resolve or create internal users as needed." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.", "deprecated": true, "x-stainless-deprecation-message": "Use 'external_user_id' instead. Internal Papr Parse user ID." }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MemoryMetadata" }, { "type": "null" } ], "description": "Metadata used in graph and vector store for a memory item. Include role and category here." }, "context": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ContextItem" }, "type": "array" }, { "type": "null" } ], "title": "Context", "description": "Conversation history context for this memory. Use for providing message history when adding a memory. Format: [{role: 'user'|'assistant', content: '...'}]" }, "relationships_json": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipItem" }, "type": "array" }, { "type": "null" } ], "title": "Relationships Json", "description": "DEPRECATED: Use 'policy' instead. Migration options: 1. Specific memory: relationships=[{source: '$this', target: 'mem_123', type: 'FOLLOWS'}] 2. Previous memory: link_to_previous_memory=True 3. Related memories: link_to_related_memories=3", "deprecated": true, "x-stainless-deprecation-message": "Use 'policy' instead." } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "AddMemoryRequest", "description": "Request model for adding a new memory", "example": { "content": "Meeting with John Smith from Acme Corp about the Q4 project timeline", "type": "text", "external_user_id": "user_alice_123", "metadata": { "topics": [ "product", "planning", "meetings" ], "hierarchical_structures": "Business/Meetings/Project Planning", "location": "Conference Room A", "emoji_tags": [ "📅", "👥", "📋" ], "emotion_tags": [ "focused", "productive" ], "conversationId": "conv-123", "sourceUrl": "https://calendar.example.com/meeting/123", "customMetadata": { "project_id": "q4-roadmap", "meeting_type": "planning" } }, "context": [ { "role": "user", "content": "Let's discuss the Q4 project timeline with John" }, { "role": "assistant", "content": "I'll help you prepare for the timeline discussion. What are your key milestones?" } ], "policy": { "consent": "implicit", "risk": "none", "transform_embedding": { "mode": "auto", "domain_id": "general" }, "graph": { "mode": "auto", "link_to": [ "Person:name~John Smith", "Company:name~Acme Corp", "Meeting:title~Q4 project timeline" ] }, "acl": { "read": [ "external_user:user_alice_123" ], "write": [ "external_user:user_alice_123" ] } } } }, "AddMemoryResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AddMemoryItem" }, "type": "array" }, { "type": "null" } ], "title": "Data", "description": "List of memory items if successful" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "additionalProperties": false, "type": "object", "title": "AddMemoryResponse", "description": "Unified response model for add_memory API endpoint (success or error)." }, "AssistantMemoryCategory": { "type": "string", "enum": [ "skills", "learning", "task", "goal", "fact", "context" ], "title": "AssistantMemoryCategory", "description": "Memory categories for assistant messages" }, "AutoGraphGeneration": { "properties": { "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id", "description": "Force AI to use this specific schema instead of auto-selecting" }, "property_overrides": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PropertyOverrideRule" }, "type": "array" }, { "type": "null" } ], "title": "Property Overrides", "description": "Override specific property values in AI-generated nodes with match conditions" } }, "type": "object", "title": "AutoGraphGeneration", "description": "AI-powered graph generation with optional guidance" }, "BatchFeedbackRequest": { "properties": { "feedback_items": { "items": { "$ref": "#/components/schemas/FeedbackRequest" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Feedback Items", "description": "List of feedback items to submit" }, "session_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Session Context", "description": "Session-level context for batch feedback" } }, "type": "object", "required": [ "feedback_items" ], "title": "BatchFeedbackRequest", "description": "Request model for submitting multiple feedback items" }, "BatchFeedbackResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code" }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'" }, "feedback_ids": { "items": { "type": "string" }, "type": "array", "title": "Feedback Ids", "description": "List of feedback IDs" }, "successful_count": { "type": "integer", "title": "Successful Count", "description": "Number of successfully processed feedback items", "default": 0 }, "failed_count": { "type": "integer", "title": "Failed Count", "description": "Number of failed feedback items", "default": 0 }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Errors", "description": "List of error details" }, "message": { "type": "string", "title": "Message", "description": "Human-readable message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if status is 'error'" } }, "type": "object", "required": [ "code", "status", "message" ], "title": "BatchFeedbackResponse", "description": "Response model for batch feedback submission" }, "BatchMemoryError": { "properties": { "index": { "type": "integer", "title": "Index" }, "error": { "type": "string", "title": "Error" }, "code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Code" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details" } }, "additionalProperties": false, "type": "object", "required": [ "index", "error" ], "title": "BatchMemoryError" }, "BatchMemoryRequest": { "properties": { "policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryAddPolicy" }, { "type": "null" } ], "description": "Unified processing policy: transform_embedding, graph, consent, risk, acl." }, "memory_policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryPolicy" }, { "type": "null" } ], "description": "DEPRECATED: Use 'policy' instead. Legacy graph + OMO policy. Use mode='auto' (LLM extraction, constraints applied if provided) or 'manual' (exact nodes). Includes consent, risk, and ACL settings. If schema_id is set, schema's memory_policy is used as defaults.", "deprecated": true }, "link_to": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Link To", "description": "DEPRECATED: Use policy.graph.link_to instead. Shorthand DSL for node/edge constraints (same as node_constraints, compact syntax). Expands and merges into memory_policy.node_constraints and edge_constraints at resolve time. Default create is upsert; use dict form with create='lookup' (or legacy 'never') for link-only. Formats: - String: 'Task:title' (semantic match on Task.title, upsert by default) - List: ['Task:title', 'Person:email'] (multiple constraints) - Dict: {'Task:title': {'set': {...}, 'create': 'lookup'}} (full options) Syntax: - Node: 'Type:property', 'Type:prop=value' (exact), 'Type:prop~value' (semantic) - Edge: 'Source->EDGE->Target:property' (arrow syntax) - Via: 'Type.via(EDGE->Target:prop)' (relationship traversal) - Special: '$this', '$previous', '$context:N' Example lookup-only: {'SecurityPolicy:name': {'create': 'lookup'}}", "deprecated": true }, "graph_generation": { "anyOf": [ { "$ref": "#/components/schemas/GraphGeneration" }, { "type": "null" } ], "description": "DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration. If both memory_policy and graph_generation are provided, memory_policy takes precedence.", "deprecated": true }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Your application's user identifier for all memories in the batch. This is the primary way to identify users. Papr will automatically resolve or create internal users as needed." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID.", "deprecated": true }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.", "deprecated": true }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this namespace." }, "memories": { "items": { "$ref": "#/components/schemas/AddMemoryRequest" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Memories", "description": "List of memory items to add in batch" }, "batch_size": { "anyOf": [ { "type": "integer", "maximum": 50, "minimum": 1 }, { "type": "null" } ], "title": "Batch Size", "description": "Number of items to process in parallel", "default": 10 }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "Optional webhook URL to notify when batch processing is complete. The webhook will receive a POST request with batch completion details." }, "webhook_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Secret", "description": "Optional secret key for webhook authentication. If provided, will be included in the webhook request headers as 'X-Webhook-Secret'." } }, "additionalProperties": true, "type": "object", "required": [ "memories" ], "title": "BatchMemoryRequest", "description": "Request model for batch adding memories", "example": { "batch_size": 10, "external_user_id": "external_user_abcde", "memories": [ { "content": "Meeting notes from the product planning session", "metadata": { "createdAt": "2024-03-21T10:00:00Z", "emoji tags": "📊,💡,📝", "emotion tags": "focused, productive", "hierarchical structures": "Business/Planning/Product", "topics": "product, planning" }, "type": "text" }, { "content": "Follow-up tasks from the planning meeting", "metadata": { "createdAt": "2024-03-21T11:00:00Z", "emoji tags": "✅,📋", "emotion tags": "organized", "hierarchical structures": "Business/Tasks/Planning", "topics": "tasks, planning" }, "type": "text" } ], "user_id": "internal_user_id_12345" } }, "BatchMemoryResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code for the batch operation", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success', 'partial', or 'error'", "default": "success" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human-readable status message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Batch-level error message, if any" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id", "description": "Batch tracking ID for status polling via GET /v1/memory/batch/status/{batch_id} and WebSocket updates" }, "successful": { "items": { "$ref": "#/components/schemas/AddMemoryResponse" }, "type": "array", "title": "Successful", "description": "List of successful add responses" }, "errors": { "items": { "$ref": "#/components/schemas/BatchMemoryError" }, "type": "array", "title": "Errors", "description": "List of errors for failed items" }, "total_processed": { "type": "integer", "title": "Total Processed", "default": 0 }, "total_successful": { "type": "integer", "title": "Total Successful", "default": 0 }, "total_failed": { "type": "integer", "title": "Total Failed", "default": 0 }, "total_content_size": { "type": "integer", "title": "Total Content Size", "default": 0 }, "total_storage_size": { "type": "integer", "title": "Total Storage Size", "default": 0 } }, "additionalProperties": false, "type": "object", "title": "BatchMemoryResponse" }, "BatchTransformItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for this item" }, "content": { "type": "string", "title": "Content", "description": "Text content for metadata extraction" }, "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding", "description": "Base embedding vector" }, "rotation_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation Embedding", "description": "Pre-computed rotation (old) embedding from holographic transform. Enables rot_v2/v3 similarity scoring and full CAESAR ensemble." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat (new) embedding from holographic transform." }, "rotation_v2_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V2 Embedding", "description": "Pre-computed rotation V2 embedding from holographic transform." }, "rotation_v3_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V3 Embedding", "description": "Pre-computed rotation V3 embedding from holographic transform." }, "context_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context Metadata", "description": "Optional context metadata for this item (createdAt, sourceType, etc.)" } }, "type": "object", "required": [ "id", "content", "embedding" ], "title": "BatchTransformItem", "description": "Single item in a batch transform request." }, "BatchTransformResultItem": { "properties": { "id": { "type": "string", "title": "Id" }, "data": { "$ref": "#/components/schemas/TransformData" } }, "type": "object", "required": [ "id", "data" ], "title": "BatchTransformResultItem", "description": "Single result in a batch transform response." }, "BatchUserCreateRequest": { "properties": { "users": { "items": { "$ref": "#/components/schemas/CreateUserRequest" }, "type": "array", "title": "Users" } }, "type": "object", "required": [ "users" ], "title": "BatchUserCreateRequest" }, "Body_upload_document_v1_document_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" }, "preferred_provider": { "anyOf": [ { "$ref": "#/components/schemas/PreferredProvider" }, { "type": "null" } ] }, "hierarchical_enabled": { "type": "boolean", "title": "Hierarchical Enabled", "default": true }, "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id" }, "graph_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Graph Override" }, "property_overrides": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Property Overrides" }, "memory_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Policy", "description": "DEPRECATED: Use 'policy' instead. JSON-encoded memory policy. Includes mode ('auto'/'manual'), schema_id, node_constraints (applied in auto mode when present), and OMO fields (consent, risk, acl).", "deprecated": true }, "policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy", "description": "JSON-encoded unified processing policy (transform_embedding, graph incl. link_to, consent, risk, acl). Applies to all chunks from this document." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id" }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Your application's user identifier. This is the primary way to identify users. Also accepts legacy 'end_user_id'." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "DEPRECATED: Internal Papr Parse user ID. Most developers should use external_user_id." }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url" }, "webhook_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Secret" }, "enable_holographic": { "type": "boolean", "title": "Enable Holographic", "description": "DEPRECATED: Use policy.transform_embedding instead. If True, applies holographic neural transforms and stores in holographic collection.", "default": false, "deprecated": true }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "DEPRECATED: Use policy.transform_embedding.domain_id instead. Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact'). Required when enable_holographic=True. Call GET /v1/frequencies to see available schemas.", "deprecated": true }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_document_v1_document_post" }, "CallbackResponse": { "properties": { "message": { "type": "string", "title": "Message", "description": "Callback status message", "default": "Authorization successful" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Authorization code" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State", "description": "State parameter for security" } }, "type": "object", "title": "CallbackResponse", "description": "Response model for OAuth2 callback endpoint" }, "CascadeDeletionResult": { "properties": { "memories_deleted": { "type": "integer", "title": "Memories Deleted", "description": "Number of memories deleted", "default": 0 }, "memories_failed": { "type": "integer", "title": "Memories Failed", "description": "Number of memories that failed to delete", "default": 0 }, "neo4j_nodes_deleted": { "type": "integer", "title": "Neo4J Nodes Deleted", "description": "Number of Neo4j nodes deleted", "default": 0 }, "acl_read_cleaned": { "type": "integer", "title": "Acl Read Cleaned", "description": "Nodes with namespace_read_access cleaned", "default": 0 }, "acl_write_cleaned": { "type": "integer", "title": "Acl Write Cleaned", "description": "Nodes with namespace_write_access cleaned", "default": 0 } }, "type": "object", "title": "CascadeDeletionResult", "description": "Details of the cascade deletion performed when a namespace is removed." }, "CatalogBufferEntry": { "properties": { "signals": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Signals", "description": "Band name -> extracted value." }, "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO timestamp of the transform call." } }, "type": "object", "required": [ "signals", "timestamp" ], "title": "CatalogBufferEntry", "description": "Raw signal snapshot from a single transform call." }, "CatalogEntityCluster": { "properties": { "label": { "type": "string", "title": "Label", "description": "LLM-chosen canonical label for this cluster." }, "members": { "items": { "type": "string" }, "type": "array", "title": "Members", "description": "Raw signal values merged into this cluster." }, "count": { "type": "integer", "title": "Count", "description": "Total occurrences across all transforms.", "default": 0 } }, "type": "object", "required": [ "label" ], "title": "CatalogEntityCluster", "description": "A cluster of semantically-similar entity values." }, "CatalogRelationshipPattern": { "properties": { "label": { "type": "string", "title": "Label", "description": "Canonical label (e.g. 'Causal', 'Preventive')." }, "members": { "items": { "type": "string" }, "type": "array", "title": "Members", "description": "Raw relationship values in this cluster." }, "count": { "type": "integer", "title": "Count", "description": "Total occurrences.", "default": 0 } }, "type": "object", "required": [ "label" ], "title": "CatalogRelationshipPattern", "description": "A cluster of semantically-similar relationship types." }, "ConsentLevel": { "type": "string", "enum": [ "explicit", "implicit", "terms", "none" ], "title": "ConsentLevel", "description": "How the data owner allowed this memory to be stored/used.\n\nAligned with Open Memory Object (OMO) standard." }, "ContextItem": { "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "title": "Role" }, "content": { "type": "string", "title": "Content" } }, "additionalProperties": false, "type": "object", "required": [ "role", "content" ], "title": "ContextItem", "description": "Context item for memory request" }, "ConversationSummaryResponse": { "properties": { "short_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Short Term", "description": "Summary of last 15 messages" }, "medium_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Medium Term", "description": "Summary of last ~100 messages" }, "long_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Long Term", "description": "Full session summary" }, "topics": { "items": { "type": "string" }, "type": "array", "title": "Topics", "description": "Key topics discussed" }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Updated", "description": "When summaries were last updated" } }, "type": "object", "title": "ConversationSummaryResponse", "description": "Hierarchical conversation summaries for context window compression" }, "CreateDomainRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Schema name in format 'company:domain:version' (e.g. 'acme:support_tickets:1.0.0')" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable description" }, "fields": { "items": { "$ref": "#/components/schemas/CustomFrequencyField" }, "type": "array", "maxItems": 14, "minItems": 1, "title": "Fields", "description": "Frequency field definitions (1-14 fields, one per frequency band)" } }, "type": "object", "required": [ "name", "fields" ], "title": "CreateDomainRequest", "description": "Request for POST /v1/holographic/domains", "example": { "description": "Support ticket classification schema", "fields": [ { "frequency": 4, "name": "priority", "type": "enum", "values": [ "P0", "P1", "P2", "P3" ], "weight": 0.9 }, { "frequency": 6, "name": "component", "type": "free_text", "weight": 0.7 }, { "frequency": 12, "name": "resolution_type", "type": "enum", "values": [ "bug_fix", "config", "wontfix" ], "weight": 0.8 } ], "name": "acme:support_tickets:1.0.0" } }, "CreateDomainResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "schema_id": { "type": "string", "title": "Schema Id", "description": "Generated schema ID" }, "domain": { "type": "string", "title": "Domain" }, "num_frequencies": { "type": "integer", "title": "Num Frequencies" } }, "type": "object", "required": [ "schema_id", "domain", "num_frequencies" ], "title": "CreateDomainResponse", "description": "Response for POST /v1/holographic/domains" }, "CreateNamespaceApiKeyRequest": { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Human-readable name for the API key (shown in admin UIs)." }, "environment": { "type": "string", "enum": [ "development", "staging", "production" ], "title": "Environment", "description": "Environment label: development, staging, or production.", "default": "production" }, "permissions": { "items": { "type": "string", "enum": [ "read", "write", "delete" ] }, "type": "array", "maxItems": 3, "minItems": 1, "title": "Permissions", "description": "Permissions granted by this key. Must be a subset of ['read', 'write', 'delete']." } }, "type": "object", "required": [ "name" ], "title": "CreateNamespaceApiKeyRequest", "description": "Request body for ``POST /v1/namespace/{namespace_id}/api-keys``.", "example": { "environment": "production", "name": "Acme Production API Key", "permissions": [ "read", "write", "delete" ] } }, "CreateNamespaceApiKeyResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceApiKeyItem" }, { "type": "null" } ], "description": "The newly created API key, including the full key string (only on creation)." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details. NEVER contains the API key." } }, "additionalProperties": false, "type": "object", "title": "CreateNamespaceApiKeyResponse", "description": "Response for ``POST /v1/namespace/{namespace_id}/api-keys``." }, "CreateNamespaceRequest": { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Namespace name (e.g., 'acme-production')" }, "environment_type": { "$ref": "#/components/schemas/EnvironmentType", "description": "Environment type: development, staging, production", "default": "production" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether this namespace is active", "default": true }, "rate_limits": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Rate Limits", "description": "Rate limits for this namespace (None values inherit from organization)" }, "default_policy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Default Policy", "description": "Default memory policy for add/search when request omits policy." } }, "type": "object", "required": [ "name" ], "title": "CreateNamespaceRequest", "description": "Request body for POST /v1/namespace", "example": { "environment_type": "production", "is_active": true, "name": "acme-production" } }, "CreateUserRequest": { "properties": { "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" }, "external_id": { "type": "string", "title": "External Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "type": { "$ref": "#/components/schemas/UserType", "default": "developerUser" } }, "type": "object", "required": [ "external_id" ], "title": "CreateUserRequest", "description": "Request model for creating a user", "example": { "email": "user@example.com", "external_id": "user123", "metadata": { "name": "John Doe", "preferences": { "theme": "dark" } }, "type": "developerUser" } }, "CustomFrequencyField": { "properties": { "frequency": { "type": "number", "title": "Frequency", "description": "Hz value (must be one of the 14 standard frequencies: 0.1, 0.5, 2.0, 4.0, 6.0, 10.0, 12.0, 18.0, 19.0, 24.0, 30.0, 40.0, 50.0, 70.0)" }, "name": { "type": "string", "title": "Name", "description": "Field name (e.g. 'ticket_priority', 'component')" }, "type": { "$ref": "#/components/schemas/FrequencyFieldType", "description": "Field type" }, "values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Values", "description": "Allowed values for enum type" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Field description" }, "weight": { "type": "number", "maximum": 1, "minimum": 0, "title": "Weight", "description": "Importance weight", "default": 1 } }, "type": "object", "required": [ "frequency", "name", "type" ], "title": "CustomFrequencyField", "description": "Single field definition for a custom frequency schema." }, "DeleteMemoryResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "memoryId": { "type": "string", "title": "Memoryid", "default": "" }, "objectId": { "type": "string", "title": "Objectid", "default": "" }, "deletion_status": { "anyOf": [ { "$ref": "#/components/schemas/DeletionStatus" }, { "type": "null" } ] }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details" } }, "additionalProperties": false, "type": "object", "title": "DeleteMemoryResponse" }, "DeleteNamespaceResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "ID of deleted namespace" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human-readable message" }, "cascade": { "anyOf": [ { "$ref": "#/components/schemas/CascadeDeletionResult" }, { "type": "null" } ], "description": "Cascade deletion details" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "additionalProperties": false, "type": "object", "title": "DeleteNamespaceResponse", "description": "Response for DELETE /v1/namespace/{namespace_id} with cascade results." }, "DeleteUserResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code" }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "ID of the user attempted to delete" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Success or error message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "type": "object", "required": [ "code", "status" ], "title": "DeleteUserResponse", "example": { "code": 200, "message": "User and association deleted successfully", "status": "success", "user_id": "abc123" } }, "DeletionStatus": { "properties": { "pinecone": { "type": "boolean", "title": "Pinecone", "default": false }, "neo4j": { "type": "boolean", "title": "Neo4J", "default": false }, "parse": { "type": "boolean", "title": "Parse", "default": false }, "qdrant": { "type": "boolean", "title": "Qdrant", "default": false }, "holographic": { "type": "boolean", "title": "Holographic", "default": false } }, "type": "object", "title": "DeletionStatus" }, "DocumentInput": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Stable doc identifier echoed back in results." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Document text (if not BYOE)." }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Pre-computed base embedding (BYOE). Qwen 2560-d expected." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Free-form user metadata, echoed back if return_documents=true." }, "signals": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Signals", "description": "Pre-extracted signal band-name -> text. If provided, the LLM extractor is skipped for this doc." }, "signal_embeddings": { "anyOf": [ { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Signal Embeddings", "description": "Pre-computed signal band-name -> vector (typically 384d sbert). If provided, per-band embedding step is skipped." }, "phases": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Phases", "description": "Pre-computed per-frequency phase angles (14-dim). If provided, phase computation is skipped." }, "rot_v3": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rot V3", "description": "Pre-computed rotation v3 vector." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat reconstruction." } }, "type": "object", "title": "DocumentInput", "description": "Object form of a document (when developer wants to attach an id/metadata).\n\nEither ``embedding`` or ``text`` should be set; both are accepted by the\nrerank pipeline. ``metadata`` round-trips into the response if requested.\n\nBYO artifact fields (``signals``, ``signal_embeddings``,\n``phases``, ``rot_v3``, ``concat_embedding``) are all optional and let\ncallers skip the per-doc extract+embed pass at scoring time. They map\n1:1 to the producer fields returned by /v1/graph/transform." }, "DocumentUploadResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success', 'processing', 'error', etc.", "default": "success" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human-readable status message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" }, "document_status": { "$ref": "#/components/schemas/DocumentUploadStatus", "description": "Status and progress of the document upload" }, "memory_items": { "items": { "$ref": "#/components/schemas/AddMemoryItem" }, "type": "array", "title": "Memory Items", "description": "List of memory items created from the document" }, "memories": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AddMemoryItem" }, "type": "array" }, { "type": "null" } ], "title": "Memories", "description": "For backward compatibility" } }, "additionalProperties": false, "type": "object", "required": [ "document_status" ], "title": "DocumentUploadResponse" }, "DocumentUploadStatus": { "properties": { "progress": { "type": "number", "title": "Progress", "description": "0.0 to 1.0 for percentage" }, "current_page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Page" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "current_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Filename" }, "upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Id" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Id", "description": "Post ID in Parse Server (user-facing page ID)" }, "status_type": { "anyOf": [ { "$ref": "#/components/schemas/DocumentUploadStatusType" }, { "type": "null" } ], "description": "Processing status type" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" } }, "additionalProperties": false, "type": "object", "required": [ "progress" ], "title": "DocumentUploadStatus" }, "DocumentUploadStatusType": { "type": "string", "enum": [ "processing", "completed", "failed", "not_found", "queued", "cancelled" ], "title": "DocumentUploadStatusType" }, "DomainSummary": { "properties": { "schema_id": { "type": "string", "title": "Schema Id" }, "name": { "type": "string", "title": "Name" }, "domain": { "type": "string", "title": "Domain" }, "description": { "type": "string", "title": "Description", "default": "" }, "num_frequencies": { "type": "integer", "title": "Num Frequencies" }, "is_custom": { "type": "boolean", "title": "Is Custom", "description": "True if created by developer via POST", "default": false } }, "type": "object", "required": [ "schema_id", "name", "domain", "num_frequencies" ], "title": "DomainSummary", "description": "Summary of an available domain." }, "EdgeConstraint-Input": { "properties": { "edge_type": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Edge Type", "description": "Edge/relationship type this constraint applies to (e.g., 'MITIGATES', 'ASSIGNED_TO'). Optional at schema level (implicit from parent UserRelationshipType), required at memory level (in memory_policy.edge_constraints)." }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type", "description": "Filter: only apply when source node is of this type. Example: source_type='SecurityBehavior' - only applies to edges from SecurityBehavior nodes." }, "target_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Type", "description": "Filter: only apply when target node is of this type. Example: target_type='TacticDef' - only applies to edges targeting TacticDef nodes." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming", "both" ], "title": "Direction", "description": "Direction of edges this constraint applies to. 'outgoing': edges where current node is source (default). 'incoming': edges where current node is target. 'both': applies in either direction.", "default": "outgoing" }, "when": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "When", "description": "Condition for when this constraint applies. Supports logical operators: '_and', '_or', '_not'. Applied to edge properties or context. Example: {'_and': [{'severity': 'high'}, {'_not': {'status': 'deprecated'}}]}" }, "create": { "type": "string", "enum": [ "upsert", "lookup", "auto", "never" ], "title": "Create", "description": "'upsert': Create target node if not found via search (default). 'lookup': Only link to existing target nodes (controlled vocabulary). When 'lookup', edges to non-existing targets are skipped. Deprecated aliases: 'auto' -> 'upsert', 'never' -> 'lookup'.", "default": "upsert" }, "on_miss": { "anyOf": [ { "type": "string", "enum": [ "create", "ignore", "error" ] }, { "type": "null" } ], "title": "On Miss", "description": "Explicit behavior when no target match found via search. 'create': create new target node (same as upsert). 'ignore': skip edge creation (same as lookup). 'error': raise error if target not found. If specified, overrides 'create' field." }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use create='lookup' instead. Shorthand for create='lookup'. When True, only links to existing target nodes. Equivalent to @lookup decorator in schema definitions.", "default": false }, "search": { "anyOf": [ { "$ref": "#/components/schemas/SearchConfig-Input" }, { "type": "null" } ], "description": "How to find/select existing target nodes for this edge. Uses SearchConfig to define matching strategy. Example: {'properties': [{'name': 'name', 'mode': 'semantic', 'threshold': 0.90}]}. For controlled vocabulary (create='never'), this defines how to find valid targets." }, "set": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/PropertyValue" } ] }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Set property values on edges. Supports: 1. Exact value: {'weight': 1.0} - sets exact value. 2. Auto-extract: {'reason': {'mode': 'auto'}} - LLM extracts from content. Edge properties are useful for relationship metadata (weight, timestamp, reason, etc.)." } }, "additionalProperties": false, "type": "object", "title": "EdgeConstraint", "description": "Policy for how edges/relationships of a specific type should be handled.\n\nUsed in two places:\n1. **Schema level**: Inside `UserRelationshipType.constraint` - `edge_type` is implicit from parent\n2. **Memory level**: In `memory_policy.edge_constraints[]` - `edge_type` is required\n\nEdge constraints allow developers to control:\n- Which edge types can be created vs. linked to existing targets\n- How to find/select target nodes (via `search`)\n- What edge property values to set (exact or auto-extracted)\n- When to apply the constraint (conditional with logical operators)\n- Filter by source/target node types\n\n**The `search` field** handles target node selection:\n- Uses SearchConfig to define how to find existing target nodes\n- Example: `{\"properties\": [{\"name\": \"name\", \"mode\": \"semantic\"}]}`\n- For controlled vocabulary: find existing target, don't create new\n\n**The `set` field** controls edge property values:\n- Exact value: `{\"weight\": 1.0}` - sets exact value\n- Auto-extract: `{\"reason\": {\"mode\": \"auto\"}}` - LLM extracts from content\n\n**The `when` field** supports logical operators (same as NodeConstraint):\n- Simple: `{\"severity\": \"high\"}`\n- AND: `{\"_and\": [{\"severity\": \"high\"}, {\"confirmed\": true}]}`\n- OR: `{\"_or\": [{\"type\": \"MITIGATES\"}, {\"type\": \"PREVENTS\"}]}`\n- NOT: `{\"_not\": {\"status\": \"deprecated\"}}`", "examples": [ { "name": "Schema Level - Controlled Vocabulary Edge", "summary": "Link to existing targets only, don't create new (edge_type implicit)", "value": { "create": "never", "search": { "properties": [ { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } } }, { "name": "Memory Level - MITIGATES Edge Constraint", "summary": "SecurityBehavior->MITIGATES->TacticDef with controlled vocabulary", "value": { "create": "never", "edge_type": "MITIGATES", "search": { "properties": [ { "name": "name", "mode": "semantic", "threshold": 0.9 } ] }, "source_type": "SecurityBehavior", "target_type": "TacticDef" } }, { "name": "Edge with Auto-Extracted Properties", "summary": "Set edge properties from content", "value": { "edge_type": "ASSIGNED_TO", "set": { "assigned_date": { "mode": "auto" }, "priority": { "mode": "auto" } } } }, { "name": "Conditional Edge Constraint", "summary": "Apply constraint only for high-severity edges", "value": { "create": "never", "edge_type": "MITIGATES", "when": { "_and": [ { "severity": "high" }, { "_not": { "status": "deprecated" } } ] } } } ] }, "EdgeConstraint-Output": { "properties": { "edge_type": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Edge Type", "description": "Edge/relationship type this constraint applies to (e.g., 'MITIGATES', 'ASSIGNED_TO'). Optional at schema level (implicit from parent UserRelationshipType), required at memory level (in memory_policy.edge_constraints)." }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type", "description": "Filter: only apply when source node is of this type. Example: source_type='SecurityBehavior' - only applies to edges from SecurityBehavior nodes." }, "target_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Type", "description": "Filter: only apply when target node is of this type. Example: target_type='TacticDef' - only applies to edges targeting TacticDef nodes." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming", "both" ], "title": "Direction", "description": "Direction of edges this constraint applies to. 'outgoing': edges where current node is source (default). 'incoming': edges where current node is target. 'both': applies in either direction.", "default": "outgoing" }, "when": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "When", "description": "Condition for when this constraint applies. Supports logical operators: '_and', '_or', '_not'. Applied to edge properties or context. Example: {'_and': [{'severity': 'high'}, {'_not': {'status': 'deprecated'}}]}" }, "create": { "type": "string", "enum": [ "upsert", "lookup", "auto", "never" ], "title": "Create", "description": "'upsert': Create target node if not found via search (default). 'lookup': Only link to existing target nodes (controlled vocabulary). When 'lookup', edges to non-existing targets are skipped. Deprecated aliases: 'auto' -> 'upsert', 'never' -> 'lookup'.", "default": "upsert" }, "on_miss": { "anyOf": [ { "type": "string", "enum": [ "create", "ignore", "error" ] }, { "type": "null" } ], "title": "On Miss", "description": "Explicit behavior when no target match found via search. 'create': create new target node (same as upsert). 'ignore': skip edge creation (same as lookup). 'error': raise error if target not found. If specified, overrides 'create' field." }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use create='lookup' instead. Shorthand for create='lookup'. When True, only links to existing target nodes. Equivalent to @lookup decorator in schema definitions.", "default": false }, "search": { "anyOf": [ { "$ref": "#/components/schemas/SearchConfig-Output" }, { "type": "null" } ], "description": "How to find/select existing target nodes for this edge. Uses SearchConfig to define matching strategy. Example: {'properties': [{'name': 'name', 'mode': 'semantic', 'threshold': 0.90}]}. For controlled vocabulary (create='never'), this defines how to find valid targets." }, "set": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/PropertyValue" } ] }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Set property values on edges. Supports: 1. Exact value: {'weight': 1.0} - sets exact value. 2. Auto-extract: {'reason': {'mode': 'auto'}} - LLM extracts from content. Edge properties are useful for relationship metadata (weight, timestamp, reason, etc.)." } }, "additionalProperties": false, "type": "object", "title": "EdgeConstraint", "description": "Policy for how edges/relationships of a specific type should be handled.\n\nUsed in two places:\n1. **Schema level**: Inside `UserRelationshipType.constraint` - `edge_type` is implicit from parent\n2. **Memory level**: In `memory_policy.edge_constraints[]` - `edge_type` is required\n\nEdge constraints allow developers to control:\n- Which edge types can be created vs. linked to existing targets\n- How to find/select target nodes (via `search`)\n- What edge property values to set (exact or auto-extracted)\n- When to apply the constraint (conditional with logical operators)\n- Filter by source/target node types\n\n**The `search` field** handles target node selection:\n- Uses SearchConfig to define how to find existing target nodes\n- Example: `{\"properties\": [{\"name\": \"name\", \"mode\": \"semantic\"}]}`\n- For controlled vocabulary: find existing target, don't create new\n\n**The `set` field** controls edge property values:\n- Exact value: `{\"weight\": 1.0}` - sets exact value\n- Auto-extract: `{\"reason\": {\"mode\": \"auto\"}}` - LLM extracts from content\n\n**The `when` field** supports logical operators (same as NodeConstraint):\n- Simple: `{\"severity\": \"high\"}`\n- AND: `{\"_and\": [{\"severity\": \"high\"}, {\"confirmed\": true}]}`\n- OR: `{\"_or\": [{\"type\": \"MITIGATES\"}, {\"type\": \"PREVENTS\"}]}`\n- NOT: `{\"_not\": {\"status\": \"deprecated\"}}`", "examples": [ { "name": "Schema Level - Controlled Vocabulary Edge", "summary": "Link to existing targets only, don't create new (edge_type implicit)", "value": { "create": "never", "search": { "properties": [ { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } } }, { "name": "Memory Level - MITIGATES Edge Constraint", "summary": "SecurityBehavior->MITIGATES->TacticDef with controlled vocabulary", "value": { "create": "never", "edge_type": "MITIGATES", "search": { "properties": [ { "name": "name", "mode": "semantic", "threshold": 0.9 } ] }, "source_type": "SecurityBehavior", "target_type": "TacticDef" } }, { "name": "Edge with Auto-Extracted Properties", "summary": "Set edge properties from content", "value": { "edge_type": "ASSIGNED_TO", "set": { "assigned_date": { "mode": "auto" }, "priority": { "mode": "auto" } } } }, { "name": "Conditional Edge Constraint", "summary": "Apply constraint only for high-severity edges", "value": { "create": "never", "edge_type": "MITIGATES", "when": { "_and": [ { "severity": "high" }, { "_not": { "status": "deprecated" } } ] } } } ] }, "EmbeddingFormat": { "type": "string", "enum": [ "int8", "float32" ], "title": "EmbeddingFormat", "description": "Embedding format options for sync tiers" }, "EnsembleMethod": { "type": "string", "enum": [ "auto", "caesar_8", "caesar_9" ], "title": "EnsembleMethod", "description": "Available ensemble methods for reranking." }, "EnvironmentType": { "type": "string", "enum": [ "development", "staging", "production" ], "title": "EnvironmentType", "description": "Environment types for namespaces" }, "ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error", "description": "Error message" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Additional error details" }, "code": { "type": "integer", "title": "Code", "description": "HTTP error code", "default": 400 } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Generic error response model" }, "FeedbackData": { "properties": { "userMessage": { "anyOf": [ { "$ref": "#/components/schemas/ParsePointer" }, { "type": "null" } ] }, "assistantMessage": { "anyOf": [ { "$ref": "#/components/schemas/ParsePointer" }, { "type": "null" } ] }, "feedbackType": { "$ref": "#/components/schemas/FeedbackType" }, "feedbackValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedbackvalue" }, "feedbackScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Feedbackscore" }, "feedbackText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedbacktext" }, "feedbackSource": { "$ref": "#/components/schemas/FeedbackSource" }, "citedMemoryIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Citedmemoryids" }, "citedNodeIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Citednodeids" }, "feedbackProcessed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Feedbackprocessed" }, "feedbackImpact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedbackimpact" } }, "type": "object", "required": [ "feedbackType", "feedbackSource" ], "title": "FeedbackData", "description": "Developer-friendly feedback data model for requests" }, "FeedbackRequest": { "properties": { "search_id": { "type": "string", "title": "Search Id", "description": "The search_id from SearchResponse that this feedback relates to" }, "feedbackData": { "$ref": "#/components/schemas/FeedbackData", "description": "The feedback data containing all feedback information" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "Internal user ID (if not provided, will be resolved from authentication)" }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "External user ID for developer API keys acting on behalf of end users" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Optional organization ID for multi-tenant feedback scoping. When provided, feedback is scoped to this organization." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant feedback scoping. When provided, feedback is scoped to this namespace." } }, "type": "object", "required": [ "search_id", "feedbackData" ], "title": "FeedbackRequest", "description": "Request model for submitting feedback on search results", "example": { "external_user_id": "dev_api_key_123", "feedbackData": { "assistantMessage": { "__type": "Pointer", "className": "PostMessage", "objectId": "abc123def456" }, "citedMemoryIds": [ "mem_123", "mem_456" ], "citedNodeIds": [ "node_123", "node_456" ], "feedbackImpact": "positive", "feedbackProcessed": true, "feedbackScore": 1, "feedbackSource": "inline", "feedbackText": "This answer was very helpful and accurate", "feedbackType": "thumbs_up", "feedbackValue": "helpful", "userMessage": { "__type": "Pointer", "className": "PostMessage", "objectId": "abc123def456" } }, "search_id": "abc123def456", "user_id": "abc123def456" } }, "FeedbackResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code" }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'" }, "feedback_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback Id", "description": "Unique feedback ID" }, "message": { "type": "string", "title": "Message", "description": "Human-readable message" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if status is 'error'" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Additional error details" } }, "type": "object", "required": [ "code", "status", "message" ], "title": "FeedbackResponse", "description": "Response model for feedback submission" }, "FeedbackSource": { "type": "string", "enum": [ "inline", "post_query", "session_end", "memory_citation", "answer_panel" ], "title": "FeedbackSource", "description": "Where the feedback was provided from" }, "FeedbackType": { "type": "string", "enum": [ "thumbs_up", "thumbs_down", "rating", "correction", "report", "copy_action", "save_action", "create_document", "memory_relevance", "answer_quality" ], "title": "FeedbackType", "description": "Types of feedback that can be provided" }, "FrequencyFieldResponse": { "properties": { "frequency_hz": { "type": "number", "title": "Frequency Hz", "description": "Frequency in Hz (brain-inspired band)" }, "name": { "type": "string", "title": "Name", "description": "Field name extracted at this frequency" }, "type": { "type": "string", "title": "Type", "description": "Field type: ENUM, FREE_TEXT, NUMERIC, DATE, MULTI_VALUE" }, "description": { "type": "string", "title": "Description", "description": "Human-readable field description", "default": "" }, "weight": { "type": "number", "title": "Weight", "description": "Default weight for this frequency band", "default": 1 } }, "type": "object", "required": [ "frequency_hz", "name", "type" ], "title": "FrequencyFieldResponse", "description": "Single frequency band definition." }, "FrequencyFieldType": { "type": "string", "enum": [ "enum", "free_text", "numeric", "boolean", "date", "sequence", "multi_value_text" ], "title": "FrequencyFieldType", "description": "Supported field types for custom frequency schemas." }, "FrequencySchemaListResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "schemas": { "items": { "$ref": "#/components/schemas/FrequencySchemaResponse" }, "type": "array", "title": "Schemas" }, "total": { "type": "integer", "title": "Total" }, "shortcuts": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Shortcuts", "description": "Shorthand aliases (e.g. 'cosqa' -> 'code_search:cosqa:2.0.0')" } }, "type": "object", "required": [ "schemas", "total" ], "title": "FrequencySchemaListResponse", "description": "Response for listing all frequency schemas." }, "FrequencySchemaResponse": { "properties": { "schema_id": { "type": "string", "title": "Schema Id", "description": "Unique schema ID (domain:name:version)" }, "name": { "type": "string", "title": "Name", "description": "Schema name" }, "domain": { "type": "string", "title": "Domain", "description": "Domain (e.g. code_search, biomedical)" }, "version": { "type": "string", "title": "Version", "description": "Schema version" }, "description": { "type": "string", "title": "Description", "description": "Human-readable description", "default": "" }, "num_frequencies": { "type": "integer", "title": "Num Frequencies", "description": "Number of frequency bands" }, "frequencies": { "items": { "$ref": "#/components/schemas/FrequencyFieldResponse" }, "type": "array", "title": "Frequencies", "description": "Frequency band definitions" }, "config": { "$ref": "#/components/schemas/SchemaConfigResponse", "description": "Operational configuration" } }, "type": "object", "required": [ "schema_id", "name", "domain", "version", "num_frequencies", "frequencies", "config" ], "title": "FrequencySchemaResponse", "description": "Full frequency schema with fields and config." }, "GraphDomainCreate": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "Custom id, e.g. 'acme:support_tickets:1.0.0'." }, "name": { "type": "string", "title": "Name", "description": "Human-readable domain name." }, "description": { "type": "string", "title": "Description", "description": "What this domain models." }, "signals": { "items": { "$ref": "#/components/schemas/SignalField" }, "type": "array", "minItems": 1, "title": "Signals", "description": "Per-domain signal definitions." }, "signal_multipliers": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers", "description": "Domain-level default signal weight multipliers. Applied automatically on every rerank/search request for this domain (unless the caller supplies their own signal_multipliers, which take priority). Keys are field names (e.g. 'key_claim') or Hz-strings (e.g. '70.0'). Values: 0.0 = disable band, 1.0 = unchanged, 2.0 = 2× boost." }, "routing_config": { "anyOf": [ { "$ref": "#/components/schemas/GraphDomainRoutingConfig" }, { "type": "null" } ], "description": "Domain-level CAESAR-VIII routing config: disabled global rules, enabled domain rule packs, optional threshold overrides." } }, "type": "object", "required": [ "domain_id", "name", "description", "signals" ], "title": "GraphDomainCreate" }, "GraphDomainDelete": { "properties": { "domain_id": { "type": "string", "title": "Domain Id" }, "deleted": { "type": "boolean", "title": "Deleted" } }, "type": "object", "required": [ "domain_id", "deleted" ], "title": "GraphDomainDelete" }, "GraphDomainList": { "properties": { "domains": { "items": { "$ref": "#/components/schemas/GraphDomainSpec" }, "type": "array", "title": "Domains" } }, "type": "object", "required": [ "domains" ], "title": "GraphDomainList" }, "GraphDomainRoutingConfig": { "properties": { "disabled_rules": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Disabled Rules", "description": "Global SciFact routing rule names to skip for this domain (e.g. 'DANGER_LOW_RSG_LOW_PHI')." }, "enabled_rule_packs": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Enabled Rule Packs", "description": "Named domain rule packs to run after global rules (e.g. 'cosqa_caesar8_v2')." }, "threshold_overrides": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Threshold Overrides", "description": "Optional CaesarConfig field overrides keyed by threshold name (e.g. {'cmas_c4_trust_jaccard_threshold': 0.95})." }, "enhanced_initial_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enhanced Initial Source", "description": "CAESAR-VIII initial source for the CE-on path. Domain defaults may pin 'caesar4_5_v4a' on code_search for public enhanced; public max overrides to 'caesar7' unless this field is set." }, "holographic_floor": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Holographic Floor", "description": "When true, never return a ranking worse than max(v4a, baseline) unless CE gate (ce_gate_min_phi) passes." }, "ce_gate_min_phi": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Ce Gate Min Phi", "description": "Minimum phi to allow caesar7/baseline_rerank to bypass holographic floor." }, "egr_lambda_ce": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Egr Lambda Ce", "description": "Stacked EGR entailment fusion weight (0–1). Lower for code domains." }, "caesar4_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caesar4 Source", "description": "Which ranking is exposed as rankings['caesar4'] to CAESAR-VIII rules (c4_c7_diverge, etc.). Accepts 'v4a' (default — alias to family-routed v4a / v3a fallback), 'v3a' (force v3a only), or 'legacy' (SKIP the alias; keep the original Jaccard / trust-score selection at rankings['caesar4'] and stash a copy at rankings['_caesar4_legacy']). Use 'legacy' to A/B C-VIII rules against the original SciFact calibration semantics. Label-free in all modes." } }, "type": "object", "title": "GraphDomainRoutingConfig", "description": "Domain-scoped CAESAR-VIII routing overrides (stored on graph_domains)." }, "GraphDomainSpec": { "properties": { "domain_id": { "type": "string", "title": "Domain Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "signals": { "items": { "$ref": "#/components/schemas/SignalField" }, "type": "array", "title": "Signals" }, "signal_multipliers": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers", "description": "Domain-level default signal multipliers (see GraphDomainCreate)." }, "routing_config": { "anyOf": [ { "$ref": "#/components/schemas/GraphDomainRoutingConfig" }, { "type": "null" } ], "description": "Domain-level CAESAR-VIII routing config (see GraphDomainRoutingConfig)." }, "builtin": { "type": "boolean", "title": "Builtin", "description": "True for built-in domains shipped with Papr (read-only).", "default": false }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "owner_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner User Id" }, "owner_workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Workspace Id", "description": "Workspace that owns this domain. Domains are scoped to workspace when set." }, "owner_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Organization Id", "description": "Organization that owns this domain." }, "owner_namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Namespace Id", "description": "Namespace this domain belongs to, if any." } }, "type": "object", "required": [ "domain_id", "name", "description", "signals" ], "title": "GraphDomainSpec" }, "GraphDomainUpdate": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Updated human-readable name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated description." }, "signal_multipliers": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers", "description": "Replace the domain-level signal_multipliers entirely. Pass an empty dict {} to clear all multipliers. Omit the field to leave existing multipliers unchanged." }, "routing_config": { "anyOf": [ { "$ref": "#/components/schemas/GraphDomainRoutingConfig" }, { "type": "null" } ], "description": "Replace the domain-level routing_config entirely. Pass null fields inside to clear. Omit to leave unchanged." } }, "type": "object", "title": "GraphDomainUpdate", "description": "Patch body for PUT /v1/graph/domains/{id}." }, "GraphGeneration": { "properties": { "mode": { "$ref": "#/components/schemas/GraphGenerationMode", "description": "Graph generation mode: 'auto' (AI-powered) or 'manual' (exact specification)", "default": "auto" }, "auto": { "anyOf": [ { "$ref": "#/components/schemas/AutoGraphGeneration" }, { "type": "null" } ], "description": "Configuration for AI-powered graph generation" }, "manual": { "anyOf": [ { "$ref": "#/components/schemas/ManualGraphGeneration" }, { "type": "null" } ], "description": "Configuration for manual graph specification" } }, "type": "object", "title": "GraphGeneration", "description": "Graph generation configuration" }, "GraphGenerationMode": { "type": "string", "enum": [ "auto", "manual" ], "title": "GraphGenerationMode", "description": "Graph generation modes" }, "GraphMeta": { "properties": { "domain_id": { "type": "string", "title": "Domain Id" }, "method_used": { "type": "string", "enum": [ "enhanced", "max", "fast" ], "title": "Method Used" }, "billed_units": { "type": "integer", "title": "Billed Units", "description": "Mini interactions consumed.", "default": 0 }, "usage": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Usage", "description": "Cohere/Voyage-compatible usage block, e.g. {'search_units': 1, 'docs_scored': 100}. Populated for /v1/graph/rerank and /v1/graph/search." }, "timing_ms": { "additionalProperties": true, "type": "object", "title": "Timing Ms", "description": "Latency breakdown in milliseconds. Top-level keys: `services_init`, `pipeline`, `total`. Optional `phases` is a nested dict with per-stage timings: query_processing, retrieval, rerank, caesar_routing." }, "debug": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Debug", "description": "Debug payload when return_debug=true. Includes: `selection_signals` (scalar routing inputs), `v3a_routing` / `v4a_routing` (method selection diagnostics), `routing_signals` (method_bgrs, method_t1lrs, pool quality), `spread_signals` (gauss/sfi/hcond spread boosters), `signal_multipliers`, `signal_weights`, `signal_weights_sparse`, `routing_config`, `domain_method_priors`, `doc_scores` (per-doc method score vectors), `router_state` (v4a EMA snapshot), `rule_fired`, `zone`, `caesar8_mode`. Per-phase timings live in `timing_ms.phases`." } }, "type": "object", "required": [ "domain_id", "method_used" ], "title": "GraphMeta" }, "GraphOverrideNode": { "properties": { "id": { "type": "string", "minLength": 1, "title": "Id", "description": "**REQUIRED**: Unique identifier for this node. Must be unique within this request. Relationships reference this via source_node_id/target_node_id. Example: 'person_john_123', 'finding_cve_2024_1234'" }, "label": { "type": "string", "minLength": 1, "title": "Label", "description": "**REQUIRED**: Node type from your UserGraphSchema. View available types at GET /v1/schemas. System types: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code" }, "properties": { "additionalProperties": true, "type": "object", "title": "Properties", "description": "**REQUIRED**: Node properties matching your UserGraphSchema definition. Must include: (1) All required properties from your schema, (2) unique_identifiers if defined (e.g., 'email' for Person) to enable MERGE deduplication. View schema requirements at GET /v1/schemas" } }, "additionalProperties": false, "type": "object", "required": [ "id", "label", "properties" ], "title": "GraphOverrideNode", "description": "Developer-specified node for graph override.\n\nIMPORTANT:\n- 'id' is REQUIRED (relationships reference nodes by these IDs)\n- 'label' must match a node type from your registered UserGraphSchema\n- 'properties' must include ALL required fields from your schema definition\n\n📋 Schema Management:\n- Register schemas: POST /v1/schemas\n- View your schemas: GET /v1/schemas", "x-schema-ref": "GET /v1/schemas" }, "GraphOverrideRelationship": { "properties": { "source_node_id": { "type": "string", "minLength": 1, "title": "Source Node Id", "description": "**REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request" }, "target_node_id": { "type": "string", "minLength": 1, "title": "Target Node Id", "description": "**REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request" }, "relationship_type": { "type": "string", "minLength": 1, "title": "Relationship Type", "description": "**REQUIRED**: Relationship type from your UserGraphSchema. View available types at GET /v1/schemas. System types: WORKS_FOR, WORKS_ON, HAS_PARTICIPANT, DISCUSSES, MENTIONS, RELATES_TO, CREATED_BY" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties", "description": "Optional relationship properties (e.g., {'since': '2024-01-01', 'role': 'manager'})" } }, "additionalProperties": false, "type": "object", "required": [ "source_node_id", "target_node_id", "relationship_type" ], "title": "GraphOverrideRelationship", "description": "Developer-specified relationship for graph override.\n\nIMPORTANT:\n- source_node_id MUST exactly match a node 'id' from the 'nodes' array\n- target_node_id MUST exactly match a node 'id' from the 'nodes' array\n- relationship_type MUST exist in your registered UserGraphSchema", "x-schema-ref": "GET /v1/schemas" }, "GraphPolicyBlock": { "properties": { "mode": { "$ref": "#/components/schemas/GraphPolicyMode", "default": "auto" }, "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id" }, "link_to": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Link To", "description": "Shorthand DSL for node/edge constraints under policy.graph. Not a separate graph mode — expands into node_constraints and edge_constraints at resolve time and merges with any explicit constraints in the same request. Default create policy is upsert (create if not found); use dict form with create='lookup' for link-only. Prefer over deprecated top-level link_to." }, "node_constraints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NodeConstraint-Input" }, "type": "array" }, { "type": "null" } ], "title": "Node Constraints", "description": "Full node constraint objects. Same rules as policy.graph.link_to after expansion; use link_to for compact DSL or this field for explicit control. Both may be set." }, "edge_constraints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EdgeConstraint-Input" }, "type": "array" }, { "type": "null" } ], "title": "Edge Constraints", "description": "Full edge constraint objects. Same rules as edge entries in policy.graph.link_to after expansion; both may be set in the same request." }, "nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NodeSpec" }, "type": "array" }, { "type": "null" } ], "title": "Nodes" }, "relationships": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipSpec" }, "type": "array" }, { "type": "null" } ], "title": "Relationships" } }, "type": "object", "title": "GraphPolicyBlock" }, "GraphPolicyMode": { "type": "string", "enum": [ "none", "auto", "manual" ], "title": "GraphPolicyMode" }, "GraphRerankRequest": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/QueryItem" } ], "title": "Query", "description": "Query text (string) or QueryItem with pre-computed artifacts." }, "documents": { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/DocumentInput" } ] }, "type": "array", "title": "Documents", "description": "Candidate documents (string or DocumentInput with pre-computed artifacts)." }, "top_k": { "anyOf": [ { "type": "integer", "maximum": 2000, "minimum": 1 }, { "type": "null" } ], "title": "Top K", "description": "Return at most this many results. Defaults to len(documents)." }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id", "description": "Domain shortname or full schema id controlling which frequency bands and extraction rules are used. Built-in shortnames: \"general\" (default), \"code\", \"cosqa\", \"codetrans\", \"codetransocean\", \"codetransocean_hybrid\", \"text2sql\", \"scifact\", \"nfcorpus\", \"fiqa\", \"legal\", \"medical\", \"ecommerce\", \"coffee_shops\". You can also pass a full schema id (e.g. \"code_search:cosqa:2.0.0\") or a custom domain_id registered via POST /v1/graph/domains.", "default": "general" }, "method": { "type": "string", "enum": [ "fast", "enhanced" ], "title": "Method", "description": "Public: enhanced (CAESAR-8) or max (CE+entailment). Accepts deprecated 'fast'/'enhanced' aliases.", "default": "fast" }, "signal_embedder": { "type": "string", "enum": [ "sbert", "qwen" ], "title": "Signal Embedder", "description": "Embedder for per-band signal vectors when extracting query/docs. 'sbert' (384d, default) is ~10x cheaper to store than 'qwen' (2560d). Must match the embedder used for any BYO signal_embeddings.", "default": "sbert" }, "signal_filters": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Filters", "description": "Hard cutoffs on per-frequency signals, e.g. {'domain_match': 0.6}. Docs below are dropped." }, "signal_multipliers": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers", "description": "Per-frequency scoring weight multipliers. Keys may be field names (e.g. 'claim_stance', 'causal_verb') or Hz-strings (e.g. '19.0'). Values: 'auto' (default) or 1.0 = unchanged, 2.0 = 2x boost, 0.0 = disable that band. Fields not specified default to 'auto'. Stacks on top of the schema-level FrequencyField.weight multipliers; request-level overrides win on conflict." }, "routing_config": { "anyOf": [ { "$ref": "#/components/schemas/GraphDomainRoutingConfig" }, { "type": "null" } ], "description": "Per-request CAESAR-VIII routing overrides. Stacks on top of domain defaults and MongoDB graph_domains.routing_config." }, "return_signal_scores": { "type": "boolean", "title": "Return Signal Scores", "description": "If true, each result carries `signal_scores` (method-level scores like `base_sim`, `caesar8_score`) and `signal_scores_by_band` (per-frequency band alignments such as `key_apis`, `language`).", "default": false }, "return_documents": { "type": "boolean", "title": "Return Documents", "description": "If true, echo back each input document in the result.", "default": false }, "return_debug": { "type": "boolean", "title": "Return Debug", "description": "If true, include CAESAR meta-signals + timing in `meta.debug`.", "default": false } }, "type": "object", "required": [ "query", "documents" ], "title": "GraphRerankRequest", "description": "Rerank candidate documents against a query.\n\nSimple usage: pass query as string and documents as strings.\n\nOptimized usage: pass query as QueryItem with pre-computed artifacts from\n/v1/graph/transform to skip LLM extraction (~10x faster)." }, "GraphRerankResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Request id for log correlation." }, "results": { "items": { "$ref": "#/components/schemas/services__holographic_embedding__graph__models__RerankResultItem" }, "type": "array", "title": "Results" }, "meta": { "$ref": "#/components/schemas/GraphMeta" } }, "type": "object", "required": [ "id", "results", "meta" ], "title": "GraphRerankResponse" }, "GraphTransformRequest": { "properties": { "text": { "type": "string", "title": "Text", "description": "Source text to transform." }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Optional caller-provided base embedding (Qwen 2560-d). If omitted, the server computes it." }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id", "description": "Domain shortname or full schema id controlling which frequency bands and extraction rules are used. Built-in shortnames: \"general\" (default), \"code\", \"cosqa\", \"codetrans\", \"codetransocean\", \"codetransocean_hybrid\", \"text2sql\", \"scifact\", \"nfcorpus\", \"fiqa\", \"legal\", \"medical\", \"ecommerce\", \"coffee_shops\". You can also pass a full schema id (e.g. \"code_search:cosqa:2.0.0\") or a custom domain_id registered via POST /v1/graph/domains." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Free-form user metadata to attach (optional, not used for scoring)." }, "signal_embedder": { "type": "string", "enum": [ "sbert", "qwen" ], "title": "Signal Embedder", "description": "Embedder for per-band signal vectors. 'sbert' (384d, default) is ~10x cheaper to store than 'qwen' (2560d, matched to base).", "default": "sbert" }, "return_rot_v3": { "type": "boolean", "title": "Return Rot V3", "description": "If true, include the rot_v3 vector in the response.", "default": false }, "return_concat": { "type": "boolean", "title": "Return Concat", "description": "If true, include the base + bands concatenation embedding.", "default": false } }, "type": "object", "required": [ "text" ], "title": "GraphTransformRequest", "description": "Producer endpoint -- turns text into all the per-doc artifacts you'd\nwant to store in any vector DB (Qdrant, pgvector, Pinecone, in-memory).\n\nAlways extracts and embeds signals for all 14 bands." }, "GraphTransformResponse": { "properties": { "phases": { "items": { "type": "number" }, "type": "array", "title": "Phases", "description": "Per-frequency phase angles (14-dim)." }, "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding", "description": "Base embedding (normalized Qwen 2560-d)." }, "signals": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Signals", "description": "Signal band-name -> extracted text (e.g. {'docstring': '...', 'function_name': '...'})." }, "signal_embeddings": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object", "title": "Signal Embeddings", "description": "Signal band-name -> embedding vector (384-d sbert or 2560-d qwen)." }, "rot_v3": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rot V3", "description": "Rotation v3 vector (only when return_rot_v3=true)." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Base + bands concatenation (only when return_concat=true)." }, "id": { "type": "string", "title": "Id", "description": "Request id for log correlation." }, "domain_id": { "type": "string", "title": "Domain Id", "description": "Domain used for extraction." }, "meta": { "additionalProperties": true, "type": "object", "title": "Meta", "description": "Timing and stats." } }, "type": "object", "required": [ "phases", "embedding", "id", "domain_id" ], "title": "GraphTransformResponse", "description": "Transform response - returns artifacts that can be passed to rerank/search.\n\nAll fields map 1:1 to DocumentInput fields for rerank." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HolographicBatchTransformRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BatchTransformItem" }, "type": "array", "maxItems": 50, "title": "Items", "description": "Items to transform (max 50)" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Domain for all items", "default": "general" }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "Schema override for all items" }, "output": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HolographicOutputField" }, "type": "array" }, { "type": "null" } ], "title": "Output", "description": "Which output fields to return for each item" } }, "type": "object", "required": [ "items" ], "title": "HolographicBatchTransformRequest", "description": "Request for POST /v1/holographic/transform/batch" }, "HolographicBatchTransformResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "results": { "items": { "$ref": "#/components/schemas/BatchTransformResultItem" }, "type": "array", "title": "Results" }, "total": { "type": "integer", "title": "Total" }, "timing_ms": { "type": "number", "title": "Timing Ms" } }, "type": "object", "required": [ "results", "total", "timing_ms" ], "title": "HolographicBatchTransformResponse", "description": "Response for POST /v1/holographic/transform/batch" }, "HolographicConfig": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether to enable holographic embedding transforms", "default": false }, "search_mode": { "$ref": "#/components/schemas/HolographicSearchMode", "description": "Search mode: 'disabled' (off), 'integrated' (search transformed embeddings), 'post_search' (fetch then rerank with H-COND)", "default": "post_search" }, "hcond_boost_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Hcond Boost Threshold", "description": "Phase alignment threshold above which to apply boost (0.0-1.0)", "default": 0.35 }, "hcond_boost_factor": { "type": "number", "maximum": 0.5, "minimum": 0, "title": "Hcond Boost Factor", "description": "Maximum boost to add for high alignment (0.0-0.5)", "default": 0.12 }, "hcond_penalty_factor": { "type": "number", "maximum": 0.5, "minimum": 0, "title": "Hcond Penalty Factor", "description": "Maximum penalty for low alignment (0.0-0.5)", "default": 0.06 }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "Frequency schema for holographic scoring. Use full ID (e.g. 'code_search:cosqa:2.0.0') or shorthand (e.g. 'cosqa'). Call GET /v1/frequencies to see available schemas and shortcuts." }, "scoring_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scoring Method", "description": "Scoring method for holographic search results. Default: 'egr_rerank' (highest accuracy, requires GPU). Options include: baseline, caesar8, egr_rerank, and 160+ others. If null, uses the schema's default_scoring_method." }, "include_frequency_scores": { "type": "boolean", "title": "Include Frequency Scores", "description": "If true, each result includes a per-frequency score breakdown showing how well the query matched the document on each dimension (e.g., programming_domain: 0.95, primary_operation: 0.72). Useful for understanding WHY a result ranked high or low.", "default": false }, "frequency_filters": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Frequency Filters", "description": "Filter results by minimum alignment on specific frequency dimensions. Keys are field names (e.g., 'programming_domain', 'primary_operation'), values are minimum alignment scores (0.0-1.0). Example: {'programming_domain': 0.8, 'primary_operation': 0.7} Only returns results that match at least 80% on domain AND 70% on operation. Call GET /v1/frequencies to see available field names for each schema." } }, "type": "object", "title": "HolographicConfig", "description": "Configuration for holographic neural embedding transforms and H-COND scoring.\n\nNeural holographic embeddings use 13 brain-inspired frequency bands to encode\nhierarchical semantic metadata alongside the base embedding. H-COND (Holographic\nCONDitional) scoring uses phase alignment for improved relevance ranking.", "example": { "enabled": true, "frequency_schema_id": "cosqa", "hcond_boost_factor": 0.12, "hcond_boost_threshold": 0.35, "hcond_penalty_factor": 0.06, "scoring_method": "egr_rerank", "search_mode": "post_search" } }, "HolographicMetadataRequest": { "properties": { "content": { "type": "string", "title": "Content", "description": "Text content for metadata extraction" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Domain for frequency schema", "default": "general" }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "Schema override" }, "rotation_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation Embedding", "description": "Pre-computed rotation (old) embedding from holographic transform. Enables rot_v2/v3 similarity scoring and full CAESAR ensemble." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat (new) embedding from holographic transform." }, "rotation_v2_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V2 Embedding", "description": "Pre-computed rotation V2 embedding from holographic transform." }, "rotation_v3_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V3 Embedding", "description": "Pre-computed rotation V3 embedding from holographic transform." }, "context_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context Metadata", "description": "Optional context metadata (createdAt, sourceType, etc.) to improve extraction." } }, "type": "object", "required": [ "content" ], "title": "HolographicMetadataRequest", "description": "Request for POST /v1/holographic/metadata (metadata-only extraction)" }, "HolographicMetadataResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "data": { "$ref": "#/components/schemas/MetadataData" } }, "type": "object", "required": [ "data" ], "title": "HolographicMetadataResponse", "description": "Response for POST /v1/holographic/metadata" }, "HolographicOutputField": { "type": "string", "enum": [ "base", "rotation_v1", "rotation_v2", "rotation_v3", "concat", "phases", "metadata", "metadata_embeddings" ], "title": "HolographicOutputField", "description": "Available output fields for the transform endpoint." }, "HolographicRerankRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "The search query text" }, "query_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Query Embedding", "description": "Query embedding in the same space as candidate embeddings. If provided, used for cosine similarity. If omitted, computed server-side (Qwen 2560d)." }, "query_phases": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Query Phases", "description": "Pre-computed query phases from a prior /transform call. If provided alongside query_embedding, skips LLM extraction entirely (hot path)." }, "query_metadata_embeddings": { "anyOf": [ { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Query Metadata Embeddings", "description": "Pre-computed query metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Required for full HCond scoring with phase alignment." }, "query_dimension_weights": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Query Dimension Weights", "description": "Pre-computed per-field weights from a prior /transform call (is_query=true). If provided, skips the adaptive Groq weights call entirely (saves ~500ms + LLM cost). Keyed by frequency string (e.g. '0.1') OR field name (e.g. 'mega_domain')." }, "candidates": { "items": { "$ref": "#/components/schemas/RerankCandidate" }, "type": "array", "maxItems": 100, "title": "Candidates", "description": "Candidate documents to rerank (max 100)" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Domain for frequency schema", "default": "general" }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "Schema override" }, "top_k": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Top K", "description": "Number of results to return", "default": 10 }, "options": { "anyOf": [ { "$ref": "#/components/schemas/RerankOptions" }, { "type": "null" } ], "description": "Reranking options" } }, "type": "object", "required": [ "query", "candidates" ], "title": "HolographicRerankRequest", "description": "Request for POST /v1/holographic/rerank", "example": { "candidates": [ { "content": "Troponin is a cardiac biomarker released during myocardial injury...", "id": "doc_1" }, { "content": "Aspirin reduces platelet aggregation...", "id": "doc_2" } ], "domain": "biomedical", "query": "How does troponin relate to myocardial infarction?", "top_k": 10 } }, "HolographicRerankResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "data": { "$ref": "#/components/schemas/RerankData" } }, "type": "object", "required": [ "data" ], "title": "HolographicRerankResponse", "description": "Response for POST /v1/holographic/rerank" }, "HolographicSearchMode": { "type": "string", "enum": [ "disabled", "integrated", "post_search" ], "title": "HolographicSearchMode", "description": "Search modes for holographic neural embeddings" }, "HolographicTransformRequest": { "properties": { "content": { "type": "string", "title": "Content", "description": "Text content for LLM metadata extraction" }, "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding", "description": "Base embedding vector (any dimensionality)" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Domain for frequency schema selection (e.g. 'biomedical', 'code', 'general')", "default": "general" }, "frequency_schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency Schema Id", "description": "Specific frequency schema ID override (e.g. 'biomedical:scifact:2.0.0'). Takes precedence over domain." }, "output": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HolographicOutputField" }, "type": "array" }, { "type": "null" } ], "title": "Output", "description": "Which output fields to return. Default: ['rotation_v3', 'metadata']. Request only what you need to minimize response size." }, "rotation_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation Embedding", "description": "Pre-computed rotation (old) embedding from holographic transform. Enables rot_v2/v3 similarity scoring and full CAESAR ensemble." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat (new) embedding from holographic transform." }, "rotation_v2_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V2 Embedding", "description": "Pre-computed rotation V2 embedding from holographic transform." }, "rotation_v3_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V3 Embedding", "description": "Pre-computed rotation V3 embedding from holographic transform." }, "context_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context Metadata", "description": "Optional context metadata (createdAt, sourceType, customMetadata, etc.) to improve LLM extraction accuracy, especially for dates and entities." }, "is_query": { "type": "boolean", "title": "Is Query", "description": "If true, treat content as a query (not a doc): runs adaptive dimension-weight scoring and returns weights in TransformData. Pass these weights into a subsequent /rerank call as `query_dimension_weights` to skip recomputation.", "default": false } }, "type": "object", "required": [ "content", "embedding" ], "title": "HolographicTransformRequest", "description": "Request for POST /v1/holographic/transform", "example": { "content": "The patient presents with elevated troponin levels indicating myocardial damage", "context_metadata": { "createdAt": "2026-03-15T14:30:00Z", "sourceType": "pubmed" }, "domain": "biomedical", "embedding": [ 0.1, -0.2, 0.3 ], "output": [ "rotation_v3", "phases", "metadata" ] } }, "HolographicTransformResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "data": { "$ref": "#/components/schemas/TransformData" } }, "type": "object", "required": [ "data" ], "title": "HolographicTransformResponse", "description": "Response for POST /v1/holographic/transform" }, "InstanceConfigInput": { "properties": { "neo4j": { "anyOf": [ { "$ref": "#/components/schemas/Neo4jInstanceConfigInput" }, { "type": "null" } ], "description": "Neo4j AuraDB instance configuration" }, "provider": { "type": "string", "title": "Provider", "description": "Cloud provider (only 'gcp' supported today)", "default": "gcp" }, "region": { "type": "string", "title": "Region", "description": "Cloud region (only 'us-west1' supported today)", "default": "us-west1" } }, "type": "object", "title": "InstanceConfigInput", "description": "Request body for setting instance configuration.", "example": { "neo4j": { "bolt_url": "neo4j+s://abc12345.databases.neo4j.io", "graphql_endpoint": "https://abc12345-graphql.production-orch-0042.neo4j.io/graphql", "password": "my-secret-password", "username": "neo4j" }, "provider": "gcp", "region": "us-west1" } }, "InstanceConfigItem": { "properties": { "neo4j": { "anyOf": [ { "$ref": "#/components/schemas/Neo4jInstanceConfigItem" }, { "type": "null" } ], "description": "Neo4j instance config" }, "provider": { "type": "string", "title": "Provider", "description": "Cloud provider" }, "region": { "type": "string", "title": "Region", "description": "Cloud region" }, "scope": { "type": "string", "title": "Scope", "description": "Where this config was resolved from: 'namespace' or 'organization'" } }, "type": "object", "required": [ "provider", "region", "scope" ], "title": "InstanceConfigItem", "description": "Instance configuration — response model for GET endpoints." }, "InstanceConfigResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/InstanceConfigItem" }, { "type": "null" } ], "description": "Instance config if successful" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional context" } }, "additionalProperties": false, "type": "object", "title": "InstanceConfigResponse", "description": "Standard response envelope for instance config operations." }, "ListDomainsResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "domains": { "items": { "$ref": "#/components/schemas/DomainSummary" }, "type": "array", "title": "Domains" }, "total": { "type": "integer", "title": "Total" }, "shortcuts": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Shortcuts", "description": "Shorthand aliases (e.g. 'cosqa' -> 'code_search:cosqa:2.0.0')" } }, "type": "object", "required": [ "domains", "total" ], "title": "ListDomainsResponse", "description": "Response for GET /v1/holographic/domains" }, "LoginResponse": { "properties": { "message": { "type": "string", "title": "Message", "default": "Redirecting to Auth0 for authentication" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Url" } }, "type": "object", "title": "LoginResponse", "description": "Response model for OAuth2 login endpoint" }, "LogoutResponse": { "properties": { "message": { "type": "string", "title": "Message", "description": "Logout status message", "default": "Redirecting to logout" }, "logout_url": { "type": "string", "title": "Logout Url", "description": "URL to complete logout process" } }, "type": "object", "required": [ "logout_url" ], "title": "LogoutResponse", "description": "Response model for logout endpoint" }, "ManualGraphGeneration": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/GraphOverrideNode" }, "type": "array", "title": "Nodes", "description": "Exact nodes to create" }, "relationships": { "items": { "$ref": "#/components/schemas/GraphOverrideRelationship" }, "type": "array", "title": "Relationships", "description": "Exact relationships to create" } }, "type": "object", "required": [ "nodes" ], "title": "ManualGraphGeneration", "description": "Complete manual control over graph structure" }, "Memory": { "properties": { "id": { "type": "string", "title": "Id" }, "content": { "type": "string", "title": "Content" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "type": { "type": "string", "title": "Type" }, "metadata": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id" }, "customMetadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custommetadata" }, "source_type": { "type": "string", "title": "Source Type", "default": "papr" }, "context": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ContextItem" }, "type": "array" }, { "type": "null" } ], "title": "Context" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "hierarchical_structures": { "type": "string", "title": "Hierarchical Structures", "default": "" }, "source_url": { "type": "string", "title": "Source Url", "default": "" }, "conversation_id": { "type": "string", "title": "Conversation Id", "default": "" }, "topics": { "items": { "type": "string" }, "type": "array", "title": "Topics" }, "steps": { "items": { "type": "string" }, "type": "array", "title": "Steps" }, "current_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Step" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "Role that generated this memory (user or assistant)" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Memory category based on role" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "acl": { "additionalProperties": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "type": "object", "title": "Acl" }, "user_id": { "type": "string", "title": "User Id" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization ID that owns this memory" }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace ID this memory belongs to" }, "source_document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Document Id" }, "source_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Message Id" }, "page_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Number" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" }, "page": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page" }, "external_user_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "External User Read Access" }, "external_user_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "External User Write Access" }, "user_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "User Read Access" }, "user_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "User Write Access" }, "workspace_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Workspace Read Access" }, "workspace_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Workspace Write Access" }, "role_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Role Read Access" }, "role_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Role Write Access" }, "namespace_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Namespace Read Access" }, "namespace_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Namespace Write Access" }, "organization_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Organization Read Access" }, "organization_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Organization Write Access" }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Full precision (float32) embedding vector from Qdrant. Typically 2560 dimensions for Qwen4B. Used for CoreML/ANE fp16 models." }, "embedding_int8": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Embedding Int8", "description": "Quantized INT8 embedding vector (values -128 to 127). 4x smaller than float32. Default format for efficiency." }, "similarity_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Similarity Score", "description": "Cosine similarity from vector search (0-1). Measures semantic relevance to query." }, "popularity_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Popularity Score", "description": "Popularity signal (0-1): 0.5*cacheConfidenceWeighted30d + 0.5*citationConfidenceWeighted30d. Uses stored EMA fields." }, "recency_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Recency Score", "description": "Recency signal (0-1): exp(-0.05 * days_since_last_access). Half-life ~14 days." }, "reranker_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reranker Score", "description": "Reranker relevance (0-1). From cross-encoder (Cohere/Qwen3/BGE) or LLM (GPT-5-nano)." }, "reranker_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reranker Confidence", "description": "Reranker confidence (0-1). Meaningful for LLM reranking; equals reranker_score for cross-encoders." }, "reranker_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reranker Type", "description": "Reranker type: 'cross_encoder' (Cohere/Qwen3/BGE) or 'llm' (GPT-5-nano/GPT-4o-mini)." }, "relevance_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Relevance Score", "description": "Final relevance (0-1). rank_results=False: 0.6*sim + 0.25*pop + 0.15*recency. rank_results=True: RRF-based fusion." }, "holographic_frequency_scores": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Holographic Frequency Scores", "description": "Per-frequency-field scores from holographic scoring (e.g. {category: 0.9, topic: 0.7}). Only present when include_frequency_scores=True." }, "metrics": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metrics" }, "totalProcessingCost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Totalprocessingcost" } }, "additionalProperties": true, "type": "object", "required": [ "id", "content", "type", "acl", "user_id" ], "title": "Memory", "description": "A memory item in the knowledge base" }, "MemoryAddPolicy": { "properties": { "consent": { "$ref": "#/components/schemas/ConsentLevel", "default": "implicit" }, "risk": { "$ref": "#/components/schemas/RiskLevel", "default": "none" }, "acl": { "anyOf": [ { "$ref": "#/components/schemas/ACLConfig" }, { "type": "null" } ] }, "transform_embedding": { "anyOf": [ { "$ref": "#/components/schemas/TransformEmbeddingPolicy" }, { "type": "null" } ] }, "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPolicyBlock" }, { "type": "null" } ] } }, "type": "object", "title": "MemoryAddPolicy", "description": "Policy for add / batch / document / message ingestion." }, "MemoryMetadata": { "properties": { "hierarchical_structures": { "anyOf": [ { "type": "string" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Hierarchical Structures", "description": "Hierarchical structures to enable navigation from broad topics to specific ones" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat", "description": "ISO datetime when the memory was created" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "topics": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Topics" }, "emoji tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Emoji Tags" }, "emotion tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Emotion Tags" }, "conversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationid" }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourceurl" }, "role": { "anyOf": [ { "$ref": "#/components/schemas/MessageRole" }, { "type": "null" } ], "description": "Role that generated this memory (user or assistant)" }, "category": { "anyOf": [ { "$ref": "#/components/schemas/UserMemoryCategory" }, { "$ref": "#/components/schemas/AssistantMemoryCategory" }, { "type": "null" } ], "title": "Category", "description": "Memory category based on role. For users: preference, task, goal, fact, context. For assistants: skills, learning, task, goal, fact, context." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "DEPRECATED: Use 'external_user_id' at request level instead. This field will be removed in v2.", "deprecated": true }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "DEPRECATED: Use 'external_user_id' at request level instead. This field will be removed in v2.", "deprecated": true }, "external_user_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "External User Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "external_user_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "External User Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "user_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "User Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "user_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "User Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "workspace_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Workspace Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "workspace_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Workspace Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "role_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Role Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "role_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Role Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "namespace_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Namespace Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "namespace_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Namespace Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "organization_read_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Organization Read Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "organization_write_access": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Organization Write Access", "description": "INTERNAL: Auto-populated for vector store filtering. Use memory_policy.acl instead." }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pageid" }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcetype" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Id", "description": "Upload ID for document processing workflows" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "DEPRECATED: Use 'organization_id' at request level instead. This field will be removed in v2.", "deprecated": true }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "DEPRECATED: Use 'namespace_id' at request level instead. This field will be removed in v2.", "deprecated": true }, "consent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consent", "description": "DEPRECATED: Use 'memory_policy.consent' at request level instead. Values: 'explicit', 'implicit' (default), 'terms', 'none'.", "default": "implicit", "deprecated": true }, "risk": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risk", "description": "DEPRECATED: Use 'memory_policy.risk' at request level instead. Values: 'none' (default), 'sensitive', 'flagged'.", "default": "none", "deprecated": true }, "acl": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Acl", "description": "DEPRECATED: Use 'memory_policy.acl' at request level instead. Format: {'read': [...], 'write': [...]}.", "deprecated": true }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionid" }, "post": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Post" }, "userMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usermessage" }, "assistantMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistantmessage" }, "relatedGoals": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relatedgoals" }, "relatedUseCases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relatedusecases" }, "relatedSteps": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relatedsteps" }, "goalClassificationScores": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Goalclassificationscores" }, "useCaseClassificationScores": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Usecaseclassificationscores" }, "stepClassificationScores": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Stepclassificationscores" }, "customMetadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ] }, "type": "object" }, { "type": "null" } ], "title": "Custommetadata", "description": "Optional object for arbitrary custom metadata fields. Only string, number, boolean, or list of strings allowed. Nested dicts are not allowed." } }, "additionalProperties": true, "type": "object", "title": "MemoryMetadata", "description": "Metadata for memory request" }, "MemoryPolicy": { "properties": { "mode": { "$ref": "#/components/schemas/PolicyMode", "description": "How to generate graph from this memory. 'auto': LLM extracts entities freely. 'manual': You provide exact nodes (no LLM). Note: 'structured' is accepted as deprecated alias for 'manual'.", "default": "auto" }, "nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NodeSpec" }, "type": "array" }, { "type": "null" } ], "title": "Nodes", "description": "For manual mode: Exact nodes to create (no LLM extraction). Required when mode='manual'. Each node needs id, type, and properties." }, "relationships": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipSpec" }, "type": "array" }, { "type": "null" } ], "title": "Relationships", "description": "Relationships between nodes. Supports special placeholders: '$this' = the Memory node being created, '$previous' = the user's most recent memory. Examples: {source: '$this', target: '$previous', type: 'FOLLOWS'} links to previous memory. {source: '$this', target: 'mem_abc', type: 'REFERENCES'} links to specific memory." }, "node_constraints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NodeConstraint-Input" }, "type": "array" }, { "type": "null" } ], "title": "Node Constraints", "description": "Rules for how LLM-extracted nodes should be created/updated. Used in 'auto' mode when present. Controls creation policy, property forcing, and merge behavior." }, "edge_constraints": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EdgeConstraint-Input" }, "type": "array" }, { "type": "null" } ], "title": "Edge Constraints", "description": "Rules for how LLM-extracted edges/relationships should be created/handled. Used in 'auto' mode when present. Controls: - create: 'auto' (create target if not found) or 'never' (controlled vocabulary) - search: How to find existing target nodes - set: Edge property values (exact or auto-extracted) - source_type/target_type: Filter by connected node types Example: {edge_type: 'MITIGATES', create: 'never', search: {properties: ['name']}}" }, "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id", "description": "Reference a UserGraphSchema by ID. The schema's memory_policy (if defined) will be used as defaults, with this request's settings taking precedence." }, "consent": { "$ref": "#/components/schemas/ConsentLevel", "description": "How the data owner allowed this memory to be stored/used. 'explicit': User explicitly agreed. 'implicit': Inferred from context (default). 'terms': Covered by Terms of Service. 'none': No consent - graph extraction will be SKIPPED.", "default": "implicit" }, "risk": { "$ref": "#/components/schemas/RiskLevel", "description": "Safety assessment for this memory. 'none': Safe content (default). 'sensitive': Contains PII or sensitive info. 'flagged': Requires review - ACL will be restricted to owner only.", "default": "none" }, "acl": { "anyOf": [ { "$ref": "#/components/schemas/ACLConfig" }, { "type": "null" } ], "description": "Access control list (ACL) for this memory and its graph nodes. Conforms to Open Memory Object (OMO) standard. Use entity prefixes: 'external_user:', 'organization:', 'namespace:', 'workspace:', 'role:', 'user:'. Example: acl=ACLConfig(read=['external_user:alice', 'organization:acme'], write=['external_user:alice']). If not provided, defaults based on external_user_id and developer. See: https://github.com/anthropics/open-memory-object" } }, "additionalProperties": false, "type": "object", "title": "MemoryPolicy", "description": "Unified memory processing policy.\n\nThis is the SINGLE source of truth for how a memory should be processed,\ncombining graph generation control AND OMO (Open Memory Object) safety standards.\n\n**Graph Generation Modes:**\n- auto: LLM extracts entities freely (default)\n- manual: Developer provides exact nodes (no LLM extraction)\n\n**OMO Safety Standards:**\n- consent: How data owner allowed storage (explicit, implicit, terms, none)\n- risk: Safety assessment (none, sensitive, flagged)\n- acl: Access control list for read/write permissions\n\n**Schema Integration:**\n- schema_id: Reference a schema that may have its own default memory_policy\n- Schema-level policies are merged with request-level (request takes precedence)", "examples": [ { "name": "Auto Mode (Default)", "summary": "LLM extracts entities freely", "value": { "mode": "auto" } }, { "name": "Manual Mode with Exact Nodes", "summary": "Developer provides exact graph structure", "value": { "mode": "manual", "nodes": [ { "id": "txn_001", "properties": { "amount": 5.5 }, "type": "Transaction" } ], "relationships": [ { "source": "txn_001", "target": "prod_001", "type": "PURCHASED" } ] } }, { "name": "Auto Mode with Constraints", "summary": "LLM extracts with your rules applied", "value": { "mode": "auto", "node_constraints": [ { "create": "never", "node_type": "Task", "set": { "status": { "apply_to": "existing", "mode": "auto" } } }, { "create": "never", "node_type": "Person" } ] } }, { "name": "Link to Previous Memory", "summary": "Use $previous placeholder in relationships", "value": { "mode": "auto", "relationships": [ { "source": "$this", "target": "$previous", "type": "FOLLOWS" } ] } }, { "name": "With OMO Safety Settings", "summary": "Explicit consent with restricted access", "value": { "acl": { "read": [ "user_alice" ], "write": [ "user_alice" ] }, "consent": "explicit", "mode": "auto", "risk": "sensitive" } }, { "name": "Using Schema Defaults", "summary": "Inherit policy from schema", "value": { "schema_id": "schema_project_mgmt_v1" } } ] }, "MemorySearchPolicy": { "properties": { "consent": { "$ref": "#/components/schemas/ConsentLevel", "default": "implicit" }, "risk": { "$ref": "#/components/schemas/RiskLevel", "default": "none" }, "vector": { "anyOf": [ { "$ref": "#/components/schemas/VectorPolicy" }, { "type": "null" } ] }, "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPolicyBlock" }, { "type": "null" } ] } }, "type": "object", "title": "MemorySearchPolicy", "description": "Policy for POST /v1/memory/search.\n\nExternal Cohere/OpenAI rerank and search-time ACL use top-level fields on\nSearchRequest (``reranking_config``, ``search_acl``) until wired here." }, "MemoryType": { "type": "string", "enum": [ "text", "code_snippet", "document" ], "title": "MemoryType", "description": "Valid memory types" }, "MessageHistoryResponse": { "properties": { "sessionId": { "type": "string", "title": "Sessionid", "description": "Session ID of the conversation" }, "messages": { "items": { "$ref": "#/components/schemas/MessageResponse" }, "type": "array", "title": "Messages", "description": "List of messages in chronological order" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of messages in the session" }, "summaries": { "anyOf": [ { "$ref": "#/components/schemas/ConversationSummaryResponse" }, { "type": "null" } ], "description": "Hierarchical conversation summaries for context compression" }, "context_for_llm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context For Llm", "description": "Pre-formatted compressed context ready for LLM consumption (summaries + recent messages)" } }, "type": "object", "required": [ "sessionId", "messages", "total_count" ], "title": "MessageHistoryResponse", "description": "Response model for retrieving message history", "example": { "context_for_llm": "FULL SESSION: Product planning and strategy conversation\nRECENT (last ~100): Ongoing product planning discussion for Q4\nCURRENT (last 15): User requested help planning Q4 product roadmap", "messages": [ { "content": "Can you help me plan the Q4 product roadmap?", "createdAt": "2024-01-15T10:30:00Z", "objectId": "msg_abc123", "processing_status": "completed", "role": "user", "sessionId": "session_123" }, { "content": "I'd be happy to help you plan your Q4 roadmap. Let's start by identifying your key objectives.", "createdAt": "2024-01-15T10:31:00Z", "objectId": "msg_def456", "processing_status": "completed", "role": "assistant", "sessionId": "session_123" } ], "sessionId": "session_123", "summaries": { "long_term": "Product planning and strategy conversation", "medium_term": "Ongoing product planning discussion for Q4", "short_term": "User requested help planning Q4 product roadmap", "topics": [ "product", "roadmap", "planning", "Q4" ] }, "total_count": 2 } }, "MessageRequest": { "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } ], "title": "Content", "description": "The content of the chat message - can be a simple string or structured content objects" }, "role": { "$ref": "#/components/schemas/MessageRole", "description": "Role of the message sender (user or assistant)" }, "sessionId": { "type": "string", "title": "Sessionid", "description": "Session ID to group related messages in a conversation" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Optional title for the conversation session. Sets the Chat.title in Parse Server for easy identification." }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MemoryMetadata" }, { "type": "null" } ], "description": "Optional metadata for the message (topics, location, etc.)" }, "context": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Context", "description": "Optional context for the message (conversation history or relevant context)" }, "relationships_json": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Relationships Json", "description": "Optional array of relationships for Graph DB (Neo4j)" }, "process_messages": { "type": "boolean", "title": "Process Messages", "description": "Whether to process messages into memories (true) or just store them (false). Default is true.", "default": true }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryAddPolicy" }, { "type": "null" } ], "description": "Unified processing policy: transform_embedding, graph (incl. link_to), consent, risk, acl." }, "memory_policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryPolicy" }, { "type": "null" } ], "description": "DEPRECATED: Use 'policy' instead. Unified policy for graph generation and OMO safety. Use mode='auto' (LLM extraction), 'manual' (exact nodes), or 'hybrid' (LLM with constraints). Includes consent, risk, and ACL settings.", "deprecated": true }, "graph_generation": { "anyOf": [ { "$ref": "#/components/schemas/GraphGeneration" }, { "type": "null" } ], "description": "DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration.", "deprecated": true }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Optional organization ID for multi-tenant message scoping" }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant message scoping" } }, "type": "object", "required": [ "content", "role", "sessionId" ], "title": "MessageRequest", "description": "Request model for storing a chat message", "examples": [ { "content": "Can you help me plan the Q4 product roadmap?", "metadata": { "location": "Office", "topics": [ "product", "planning", "roadmap" ] }, "process_messages": true, "role": "user", "sessionId": "session_123", "title": "Q4 Product Planning" }, { "content": [ { "text": "Here's a story about a character trapped in an emerald egg...", "type": "text" } ], "metadata": { "location": "Home", "topics": [ "creative", "storytelling" ] }, "process_messages": true, "role": "user", "sessionId": "session_456", "title": "Creative Writing Session" } ] }, "MessageResponse": { "properties": { "objectId": { "type": "string", "title": "Objectid", "description": "Parse Server objectId of the stored message" }, "sessionId": { "type": "string", "title": "Sessionid", "description": "Session ID of the conversation" }, "role": { "$ref": "#/components/schemas/MessageRole" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } ], "title": "Content", "description": "Content of the message - can be a simple string or structured content objects" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When the message was created" }, "processing_status": { "type": "string", "title": "Processing Status", "description": "Status of background processing (queued, analyzing, completed, failed)", "default": "queued" } }, "type": "object", "required": [ "objectId", "sessionId", "role", "content", "createdAt" ], "title": "MessageResponse", "description": "Response model for message storage", "example": { "content": "Can you help me plan the Q4 product roadmap?", "createdAt": "2024-01-15T10:30:00Z", "objectId": "msg_abc123", "processing_status": "queued", "role": "user", "sessionId": "session_123" } }, "MessageRole": { "type": "string", "enum": [ "user", "assistant" ], "title": "MessageRole", "description": "Role of the message sender" }, "MetadataData": { "properties": { "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "LLM-extracted metadata keyed by frequency field name" }, "phases": { "items": { "type": "number" }, "type": "array", "title": "Phases", "description": "14 phase values for on-device transform" }, "domain": { "type": "string", "title": "Domain" }, "frequency_schema_id": { "type": "string", "title": "Frequency Schema Id" }, "timing_ms": { "type": "number", "title": "Timing Ms" } }, "type": "object", "required": [ "metadata", "phases", "domain", "frequency_schema_id", "timing_ms" ], "title": "MetadataData" }, "NamespaceApiKeyItem": { "properties": { "objectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Objectid", "description": "Parse APIKey objectId" }, "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key", "description": "The full API key string. Returned ONLY on creation; store it securely — you cannot retrieve it later." }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Prefix", "description": "First 24 characters of the key, safe for audit/UI display." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable name" }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Bound namespace objectId" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Bound organization objectId" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment label" }, "permissions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Permissions", "description": "Granted permissions" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether this key is active" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat", "description": "Creation timestamp (ISO 8601)" } }, "additionalProperties": true, "type": "object", "title": "NamespaceApiKeyItem", "description": "Public-facing API key data.\n\nThe ``key`` field is populated **only** in the response of\n``POST /v1/namespace/{namespace_id}/api-keys`` (the moment of creation).\nIt is never returned by any read/list endpoint and is never logged.\nUse ``key_prefix`` (first 24 chars) to identify the key in audit trails\nand admin dashboards." }, "NamespaceItem": { "properties": { "objectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Objectid", "description": "Parse objectId" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Namespace name" }, "environment_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Type", "description": "Environment type" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether namespace is active" }, "rate_limits": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Rate Limits", "description": "Rate limits" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Owning organization ID" }, "instance_config": { "anyOf": [ { "$ref": "#/components/schemas/InstanceConfigItem" }, { "type": "null" } ], "description": "Dedicated instance configuration (masked). None = inherits from organization or uses shared." }, "default_policy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Default Policy", "description": "Default memory policy when requests omit policy." }, "storageCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Storagecount", "description": "Total storage items" }, "memoriesCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Memoriescount", "description": "Total memories" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat", "description": "Creation timestamp" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updatedat", "description": "Last update timestamp" } }, "additionalProperties": true, "type": "object", "title": "NamespaceItem", "description": "Public-facing namespace data returned in API responses." }, "NamespaceListResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NamespaceItem" }, "type": "array" }, { "type": "null" } ], "title": "Data", "description": "List of namespaces" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total matching namespaces" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "Current page (0-indexed skip)" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size", "description": "Items per page" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "additionalProperties": false, "type": "object", "title": "NamespaceListResponse", "description": "Response for listing namespaces with pagination." }, "NamespaceResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceItem" }, { "type": "null" } ], "description": "Namespace data if successful" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "additionalProperties": false, "type": "object", "title": "NamespaceResponse", "description": "Response for single-namespace operations (create, get, update)." }, "Neo4jInstanceConfigInput": { "properties": { "bolt_url": { "type": "string", "title": "Bolt Url", "description": "Neo4j bolt connection URL (e.g. 'neo4j+s://xxxxx.databases.neo4j.io')" }, "username": { "type": "string", "title": "Username", "description": "Neo4j username", "default": "neo4j" }, "password": { "type": "string", "title": "Password", "description": "Neo4j password (encrypted before storage)" }, "graphql_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Graphql Endpoint", "description": "Neo4j hosted GraphQL endpoint URL (e.g. 'https://xxxxx-graphql.production-orch-xxxx.neo4j.io/graphql')" } }, "type": "object", "required": [ "bolt_url", "password" ], "title": "Neo4jInstanceConfigInput", "description": "Neo4j AuraDB instance configuration — input (plain password).", "example": { "bolt_url": "neo4j+s://abc12345.databases.neo4j.io", "graphql_endpoint": "https://abc12345-graphql.production-orch-0042.neo4j.io/graphql", "password": "my-secret-password", "username": "neo4j" } }, "Neo4jInstanceConfigItem": { "properties": { "bolt_url": { "type": "string", "title": "Bolt Url", "description": "Neo4j bolt connection URL" }, "username": { "type": "string", "title": "Username", "description": "Neo4j username" }, "password_masked": { "type": "string", "title": "Password Masked", "description": "Masked password (e.g. '****ab12')" }, "graphql_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Graphql Endpoint", "description": "Neo4j GraphQL endpoint URL" } }, "type": "object", "required": [ "bolt_url", "username", "password_masked" ], "title": "Neo4jInstanceConfigItem", "description": "Neo4j instance configuration — response (password masked)." }, "Node": { "properties": { "label": { "type": "string", "title": "Label", "description": "Node type label - can be system type (Memory, Person, etc.) or custom type from UserGraphSchema" }, "properties": { "additionalProperties": true, "type": "object", "title": "Properties", "description": "Node properties - structure depends on node type and schema" }, "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id", "description": "Reference to UserGraphSchema ID for custom nodes. Use GET /v1/schemas/{schema_id} to get full schema definition. Null for system nodes." } }, "type": "object", "required": [ "label", "properties" ], "title": "Node", "description": "Public-facing node structure - supports both system and custom schema nodes", "examples": [ { "name": "System Node Example", "summary": "Standard system node (Person)", "value": { "label": "Person", "properties": { "id": "person-123", "name": "John Doe", "role": "Manager", "user_id": "user-456" } } }, { "name": "Custom Node Example", "summary": "Custom schema node (Developer)", "value": { "label": "Developer", "properties": { "id": "dev-789", "name": "Rachel Green", "expertise": [ "React", "TypeScript" ], "years_experience": 5, "user_id": "user-456" }, "schema_id": "schema_abc123" } } ] }, "NodeConstraint-Input": { "properties": { "node_type": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Node Type", "description": "Node type this constraint applies to (e.g., 'Task', 'Project', 'Person'). Optional at schema level (implicit from parent UserNodeType), required at memory level (in memory_policy.node_constraints)." }, "when": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "When", "description": "Condition for when this constraint applies. Supports logical operators: '_and', '_or', '_not'. Examples: Simple: {'priority': 'high'} - matches when priority equals 'high'. AND: {'_and': [{'priority': 'high'}, {'status': 'active'}]} - all must match. OR: {'_or': [{'status': 'active'}, {'status': 'pending'}]} - any must match. NOT: {'_not': {'status': 'completed'}} - negation. Complex: {'_and': [{'priority': 'high'}, {'_or': [{'status': 'active'}, {'urgent': true}]}]}" }, "create": { "type": "string", "enum": [ "upsert", "lookup", "auto", "never" ], "title": "Create", "description": "'upsert': Create if not found via search (default). 'lookup': Only link to existing nodes (controlled vocabulary). Deprecated aliases: 'auto' -> 'upsert', 'never' -> 'lookup'.", "default": "upsert" }, "on_miss": { "anyOf": [ { "type": "string", "enum": [ "create", "ignore", "error" ] }, { "type": "null" } ], "title": "On Miss", "description": "Explicit behavior when no match found via search. 'create': create new node (same as upsert). 'ignore': skip node creation (same as lookup). 'error': raise error if node not found. If specified, overrides 'create' field." }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use create='lookup' instead. Shorthand for create='lookup'. When True, only links to existing nodes (controlled vocabulary). Equivalent to @lookup decorator in schema definitions.", "default": false }, "search": { "anyOf": [ { "$ref": "#/components/schemas/SearchConfig-Input" }, { "type": "null" } ], "description": "How to find/select existing nodes. Uses PropertyMatch list to define: 1. Which properties are unique identifiers 2. How to match on each (exact, semantic, fuzzy) 3. Order of matching (first match wins). Example: {'properties': [{'name': 'id', 'mode': 'exact'}, {'name': 'title', 'mode': 'semantic'}]}. For direct node selection, use PropertyMatch with value: {'properties': [{'name': 'id', 'mode': 'exact', 'value': 'proj_123'}]}" }, "set": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/PropertyValue" } ] }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Set property values on nodes. Supports: 1. Exact value: {'status': 'done'} - sets exact value. 2. Auto-extract: {'status': {'mode': 'auto'}} - LLM extracts from content. 3. Text mode: {'summary': {'mode': 'auto', 'text_mode': 'merge'}} - controls text updates. For text properties, text_mode can be 'replace', 'append', or 'merge'." } }, "additionalProperties": false, "type": "object", "title": "NodeConstraint", "description": "Policy for how nodes of a specific type should be handled.\n\nUsed in two places:\n1. **Schema level**: Inside `UserNodeType.constraint` - `node_type` is implicit from parent\n2. **Memory level**: In `memory_policy.node_constraints[]` - `node_type` is required\n\nNode constraints allow developers to control:\n- Which node types can be created vs. linked\n- How to find/select existing nodes (via `search`)\n- What property values to set (exact or auto-extracted)\n- When to apply the constraint (conditional with logical operators)\n\n**The `search` field** handles node selection:\n- Uses PropertyMatch list to define unique identifiers and matching strategy\n- Example: `{\"properties\": [{\"name\": \"id\", \"mode\": \"exact\"}, {\"name\": \"title\", \"mode\": \"semantic\"}]}`\n- For direct selection, use PropertyMatch with value: `{\"name\": \"id\", \"mode\": \"exact\", \"value\": \"proj_123\"}`\n\n**The `set` field** controls property values:\n- Exact value: `{\"status\": \"done\"}` - sets exact value\n- Auto-extract: `{\"status\": {\"mode\": \"auto\"}}` - LLM extracts from content\n\n**The `when` field** supports logical operators:\n- Simple: `{\"priority\": \"high\"}`\n- AND: `{\"_and\": [{\"priority\": \"high\"}, {\"status\": \"active\"}]}`\n- OR: `{\"_or\": [{\"status\": \"active\"}, {\"status\": \"pending\"}]}`\n- NOT: `{\"_not\": {\"status\": \"completed\"}}`\n- Complex: `{\"_and\": [{\"priority\": \"high\"}, {\"_or\": [{\"status\": \"active\"}, {\"urgent\": true}]}]}`", "examples": [ { "name": "Schema Level - Task with Multiple Match Strategies", "summary": "Define unique identifiers for Task nodes (node_type implicit at schema level)", "value": { "create": "auto", "search": { "properties": [ { "name": "id", "mode": "exact" }, { "name": "title", "mode": "semantic", "threshold": 0.85 } ] } } }, { "name": "Memory Level - Select Specific Node", "summary": "Use PropertyMatch with value for direct selection", "value": { "node_type": "Task", "search": { "properties": [ { "name": "id", "mode": "exact", "value": "TASK-123" } ] }, "set": { "status": { "mode": "auto" } } } }, { "name": "Memory Level - Semantic Search with Value", "summary": "Search for nodes matching a description", "value": { "node_type": "Task", "search": { "properties": [ { "name": "title", "mode": "semantic", "value": "authentication bug" } ] } } }, { "name": "Controlled Vocabulary with Auto-Extract", "summary": "Link to existing nodes only, update properties from AI", "value": { "create": "never", "node_type": "Person", "search": { "properties": [ { "name": "email", "mode": "exact" }, { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } } }, { "name": "Conditional with Logical Operators", "summary": "Apply constraint only when conditions match", "value": { "create": "never", "node_type": "Task", "set": { "urgent": true }, "when": { "_and": [ { "priority": "high" }, { "_not": { "status": "completed" } } ] } } }, { "name": "Text Merge Mode", "summary": "Merge new content with existing text", "value": { "node_type": "Document", "set": { "summary": { "mode": "auto", "text_mode": "merge" } } } } ] }, "NodeConstraint-Output": { "properties": { "node_type": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Node Type", "description": "Node type this constraint applies to (e.g., 'Task', 'Project', 'Person'). Optional at schema level (implicit from parent UserNodeType), required at memory level (in memory_policy.node_constraints)." }, "when": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "When", "description": "Condition for when this constraint applies. Supports logical operators: '_and', '_or', '_not'. Examples: Simple: {'priority': 'high'} - matches when priority equals 'high'. AND: {'_and': [{'priority': 'high'}, {'status': 'active'}]} - all must match. OR: {'_or': [{'status': 'active'}, {'status': 'pending'}]} - any must match. NOT: {'_not': {'status': 'completed'}} - negation. Complex: {'_and': [{'priority': 'high'}, {'_or': [{'status': 'active'}, {'urgent': true}]}]}" }, "create": { "type": "string", "enum": [ "upsert", "lookup", "auto", "never" ], "title": "Create", "description": "'upsert': Create if not found via search (default). 'lookup': Only link to existing nodes (controlled vocabulary). Deprecated aliases: 'auto' -> 'upsert', 'never' -> 'lookup'.", "default": "upsert" }, "on_miss": { "anyOf": [ { "type": "string", "enum": [ "create", "ignore", "error" ] }, { "type": "null" } ], "title": "On Miss", "description": "Explicit behavior when no match found via search. 'create': create new node (same as upsert). 'ignore': skip node creation (same as lookup). 'error': raise error if node not found. If specified, overrides 'create' field." }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use create='lookup' instead. Shorthand for create='lookup'. When True, only links to existing nodes (controlled vocabulary). Equivalent to @lookup decorator in schema definitions.", "default": false }, "search": { "anyOf": [ { "$ref": "#/components/schemas/SearchConfig-Output" }, { "type": "null" } ], "description": "How to find/select existing nodes. Uses PropertyMatch list to define: 1. Which properties are unique identifiers 2. How to match on each (exact, semantic, fuzzy) 3. Order of matching (first match wins). Example: {'properties': [{'name': 'id', 'mode': 'exact'}, {'name': 'title', 'mode': 'semantic'}]}. For direct node selection, use PropertyMatch with value: {'properties': [{'name': 'id', 'mode': 'exact', 'value': 'proj_123'}]}" }, "set": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/PropertyValue" } ] }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Set property values on nodes. Supports: 1. Exact value: {'status': 'done'} - sets exact value. 2. Auto-extract: {'status': {'mode': 'auto'}} - LLM extracts from content. 3. Text mode: {'summary': {'mode': 'auto', 'text_mode': 'merge'}} - controls text updates. For text properties, text_mode can be 'replace', 'append', or 'merge'." } }, "additionalProperties": false, "type": "object", "title": "NodeConstraint", "description": "Policy for how nodes of a specific type should be handled.\n\nUsed in two places:\n1. **Schema level**: Inside `UserNodeType.constraint` - `node_type` is implicit from parent\n2. **Memory level**: In `memory_policy.node_constraints[]` - `node_type` is required\n\nNode constraints allow developers to control:\n- Which node types can be created vs. linked\n- How to find/select existing nodes (via `search`)\n- What property values to set (exact or auto-extracted)\n- When to apply the constraint (conditional with logical operators)\n\n**The `search` field** handles node selection:\n- Uses PropertyMatch list to define unique identifiers and matching strategy\n- Example: `{\"properties\": [{\"name\": \"id\", \"mode\": \"exact\"}, {\"name\": \"title\", \"mode\": \"semantic\"}]}`\n- For direct selection, use PropertyMatch with value: `{\"name\": \"id\", \"mode\": \"exact\", \"value\": \"proj_123\"}`\n\n**The `set` field** controls property values:\n- Exact value: `{\"status\": \"done\"}` - sets exact value\n- Auto-extract: `{\"status\": {\"mode\": \"auto\"}}` - LLM extracts from content\n\n**The `when` field** supports logical operators:\n- Simple: `{\"priority\": \"high\"}`\n- AND: `{\"_and\": [{\"priority\": \"high\"}, {\"status\": \"active\"}]}`\n- OR: `{\"_or\": [{\"status\": \"active\"}, {\"status\": \"pending\"}]}`\n- NOT: `{\"_not\": {\"status\": \"completed\"}}`\n- Complex: `{\"_and\": [{\"priority\": \"high\"}, {\"_or\": [{\"status\": \"active\"}, {\"urgent\": true}]}]}`", "examples": [ { "name": "Schema Level - Task with Multiple Match Strategies", "summary": "Define unique identifiers for Task nodes (node_type implicit at schema level)", "value": { "create": "auto", "search": { "properties": [ { "name": "id", "mode": "exact" }, { "name": "title", "mode": "semantic", "threshold": 0.85 } ] } } }, { "name": "Memory Level - Select Specific Node", "summary": "Use PropertyMatch with value for direct selection", "value": { "node_type": "Task", "search": { "properties": [ { "name": "id", "mode": "exact", "value": "TASK-123" } ] }, "set": { "status": { "mode": "auto" } } } }, { "name": "Memory Level - Semantic Search with Value", "summary": "Search for nodes matching a description", "value": { "node_type": "Task", "search": { "properties": [ { "name": "title", "mode": "semantic", "value": "authentication bug" } ] } } }, { "name": "Controlled Vocabulary with Auto-Extract", "summary": "Link to existing nodes only, update properties from AI", "value": { "create": "never", "node_type": "Person", "search": { "properties": [ { "name": "email", "mode": "exact" }, { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } } }, { "name": "Conditional with Logical Operators", "summary": "Apply constraint only when conditions match", "value": { "create": "never", "node_type": "Task", "set": { "urgent": true }, "when": { "_and": [ { "priority": "high" }, { "_not": { "status": "completed" } } ] } } }, { "name": "Text Merge Mode", "summary": "Merge new content with existing text", "value": { "node_type": "Document", "set": { "summary": { "mode": "auto", "text_mode": "merge" } } } } ] }, "NodeSpec": { "properties": { "id": { "type": "string", "minLength": 1, "title": "Id", "description": "Unique identifier for this node" }, "type": { "type": "string", "minLength": 1, "title": "Type", "description": "Node type/label (e.g., 'Transaction', 'Product', 'Person')" }, "properties": { "additionalProperties": true, "type": "object", "title": "Properties", "description": "Properties for this node" } }, "additionalProperties": false, "type": "object", "required": [ "id", "type" ], "title": "NodeSpec", "description": "Specification for a node in manual mode.\n\nUsed when mode='manual' to define exact nodes to create.", "examples": [ { "id": "txn_12345", "properties": { "amount": 5.5, "product": "Latte", "timestamp": "2026-01-21T10:30:00Z" }, "type": "Transaction" } ] }, "OMOExportRequest": { "properties": { "memory_ids": { "items": { "type": "string" }, "type": "array", "title": "Memory Ids", "description": "List of memory IDs to export" } }, "type": "object", "required": [ "memory_ids" ], "title": "OMOExportRequest", "description": "Request model for exporting memories to OMO format." }, "OMOExportResponse": { "properties": { "code": { "type": "integer", "title": "Code", "default": 200 }, "status": { "type": "string", "title": "Status", "default": "success" }, "count": { "type": "integer", "title": "Count", "description": "Number of memories exported" }, "memories": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Memories", "description": "Memories in OMO v1 format" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "count", "memories" ], "title": "OMOExportResponse", "description": "Response model for OMO export." }, "OMOFilter": { "properties": { "min_consent": { "anyOf": [ { "$ref": "#/components/schemas/ConsentLevel" }, { "type": "null" } ], "description": "Minimum consent level required. Excludes memories with lower consent levels. Order: explicit > implicit > terms > none. Example: min_consent='implicit' excludes 'none' consent memories." }, "exclude_consent": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ConsentLevel" }, "type": "array" }, { "type": "null" } ], "title": "Exclude Consent", "description": "Explicitly exclude memories with these consent levels. Example: exclude_consent=['none'] filters out all memories without consent." }, "max_risk": { "anyOf": [ { "$ref": "#/components/schemas/RiskLevel" }, { "type": "null" } ], "description": "Maximum risk level allowed. Excludes memories with higher risk. Order: none < sensitive < flagged. Example: max_risk='none' excludes 'sensitive' and 'flagged' memories." }, "exclude_risk": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RiskLevel" }, "type": "array" }, { "type": "null" } ], "title": "Exclude Risk", "description": "Explicitly exclude memories with these risk levels. Example: exclude_risk=['flagged'] filters out all flagged content." }, "require_consent": { "type": "boolean", "title": "Require Consent", "description": "If true, only return memories with explicit consent (consent != 'none'). Shorthand for exclude_consent=['none'].", "default": false }, "exclude_flagged": { "type": "boolean", "title": "Exclude Flagged", "description": "If true, exclude all flagged content (risk == 'flagged'). Shorthand for exclude_risk=['flagged'].", "default": false } }, "additionalProperties": false, "type": "object", "title": "OMOFilter", "description": "Filter for Open Memory Object (OMO) safety standards in search/retrieval.\n\nUse this to filter search results by consent level and/or risk level.", "examples": [ { "exclude_flagged": true, "require_consent": true }, { "max_risk": "sensitive", "min_consent": "implicit" }, { "exclude_consent": [ "none" ], "exclude_risk": [ "flagged" ] } ] }, "OMOImportRequest": { "properties": { "memories": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Memories", "description": "List of memories in OMO v1 format" }, "skip_duplicates": { "type": "boolean", "title": "Skip Duplicates", "description": "Skip memories with IDs that already exist", "default": true } }, "type": "object", "required": [ "memories" ], "title": "OMOImportRequest", "description": "Request model for importing memories from OMO format." }, "OMOImportResponse": { "properties": { "code": { "type": "integer", "title": "Code", "default": 200 }, "status": { "type": "string", "title": "Status", "default": "success" }, "imported": { "type": "integer", "title": "Imported", "description": "Number of memories successfully imported" }, "skipped": { "type": "integer", "title": "Skipped", "description": "Number of memories skipped (duplicates)", "default": 0 }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Errors", "description": "Import errors" }, "memory_ids": { "items": { "type": "string" }, "type": "array", "title": "Memory Ids", "description": "IDs of imported memories" } }, "type": "object", "required": [ "imported" ], "title": "OMOImportResponse", "description": "Response model for OMO import." }, "ParsePointer": { "properties": { "objectId": { "type": "string", "title": "Objectid" }, "__type": { "type": "string", "title": "Type", "default": "Pointer" }, "className": { "type": "string", "title": "Classname" } }, "additionalProperties": false, "type": "object", "required": [ "objectId", "className" ], "title": "ParsePointer", "description": "A pointer to a Parse object" }, "PolicyMode": { "type": "string", "enum": [ "auto", "manual" ], "title": "PolicyMode", "description": "Memory processing mode - describes WHO controls graph generation.\n\n- AUTO: LLM extracts entities freely (default)\n- MANUAL: Developer provides exact nodes (no LLM extraction)\n\nNote: 'structured' is accepted as a deprecated alias for 'manual'." }, "PreferredProvider": { "type": "string", "enum": [ "gemini", "tensorlake", "reducto", "auto" ], "title": "PreferredProvider", "description": "Preferred provider for document processing." }, "PropertyDefinition": { "properties": { "type": { "$ref": "#/components/schemas/PropertyType" }, "required": { "type": "boolean", "title": "Required", "default": false }, "default": { "anyOf": [ {}, { "type": "null" } ], "title": "Default" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "min_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Length" }, "max_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Length" }, "min_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Value" }, "max_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Value" }, "enum_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 15 }, { "type": "null" } ], "title": "Enum Values", "description": "List of allowed enum values (max 15)" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "PropertyDefinition", "description": "Property definition for nodes/relationships" }, "PropertyMatch": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name", "description": "Property name to match on (e.g., 'id', 'email', 'title')" }, "mode": { "$ref": "#/components/schemas/SearchMode", "description": "Matching mode: 'exact' (string match), 'semantic' (embedding similarity), 'fuzzy' (Levenshtein distance)", "default": "exact" }, "threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Threshold", "description": "Similarity threshold for semantic/fuzzy modes (0.0-1.0). Ignored for exact mode.", "default": 0.85 }, "value": { "anyOf": [ {}, { "type": "null" } ], "title": "Value", "description": "Runtime value override. If set, use this value for matching instead of extracting from content. Useful for memory-level overrides when you know the exact value to search for." } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "PropertyMatch", "description": "Property matching configuration.\n\nDefines which property to match on and how.\nWhen listed in search.properties, this property becomes a unique identifier.\n\n**Shorthand Helpers** (recommended for common cases):\n PropertyMatch.exact(\"id\") # Exact match on id\n PropertyMatch.exact(\"id\", \"TASK-123\") # Exact match with specific value\n PropertyMatch.semantic(\"title\") # Semantic match with default threshold\n PropertyMatch.semantic(\"title\", 0.9) # Semantic match with custom threshold\n PropertyMatch.semantic(\"title\", value=\"bug\") # Semantic search for \"bug\"\n PropertyMatch.fuzzy(\"name\", 0.8) # Fuzzy match\n\n**Full Form** (when you need all options):\n PropertyMatch(name=\"title\", mode=\"semantic\", threshold=0.9, value=\"auth bug\")\n\n**String Shorthand** (in SearchConfig.properties):\n properties=[\"id\", \"email\"] # Equivalent to [PropertyMatch.exact(\"id\"), PropertyMatch.exact(\"email\")]", "examples": [ { "name": "Exact ID match", "value": { "mode": "exact", "name": "id" } }, { "name": "Semantic title match", "value": { "mode": "semantic", "name": "title", "threshold": 0.85 } }, { "name": "Memory-level with specific value", "value": { "mode": "exact", "name": "id", "value": "TASK-123" } }, { "name": "Semantic search for specific text", "value": { "mode": "semantic", "name": "title", "value": "authentication bug" } } ] }, "PropertyOverrideRule": { "properties": { "nodeLabel": { "type": "string", "minLength": 1, "title": "Nodelabel", "description": "Node type to apply overrides to (e.g., 'User', 'SecurityBehavior')" }, "match": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Match", "description": "Optional conditions that must be met for override to apply. If not provided, applies to all nodes of this type" }, "set": { "additionalProperties": true, "type": "object", "title": "Set", "description": "Properties to set/override on matching nodes" } }, "additionalProperties": false, "type": "object", "required": [ "nodeLabel", "set" ], "title": "PropertyOverrideRule", "description": "Property override rule with optional match conditions", "examples": [ { "match": { "name": "Alice" }, "nodeLabel": "User", "set": { "id": "user_alice_123", "role": "project_manager" } }, { "nodeLabel": "Note", "set": { "archived": false, "pageId": "pg_123" } } ] }, "PropertyType": { "type": "string", "enum": [ "string", "integer", "float", "boolean", "array", "datetime", "object" ], "title": "PropertyType" }, "PropertyValue": { "properties": { "mode": { "type": "string", "const": "auto", "title": "Mode", "description": "'auto': LLM extracts value from memory content.", "default": "auto" }, "text_mode": { "$ref": "#/components/schemas/TextMode", "description": "For text properties: 'replace' (overwrite), 'append' (add to), 'merge' (LLM combines existing + new).", "default": "replace" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "Custom extraction prompt for this field. Guides the LLM on what to extract and how to format it. Example: 'Summarize in 1-2 sentences with attack vector and affected systems.'" } }, "additionalProperties": false, "type": "object", "title": "PropertyValue", "description": "Configuration for a property value in NodeConstraint.set.\n\nSupports two modes:\n1. Exact value: Just pass the value directly (e.g., \"done\", 123, True)\n2. Auto-extract: {\"mode\": \"auto\"} - LLM extracts from memory content\n\nFor text properties, use text_mode to control how updates are applied.\nUse prompt to provide per-field extraction guidance to the LLM.", "examples": [ { "mode": "auto" }, { "mode": "auto", "text_mode": "merge" }, { "mode": "auto", "prompt": "Summarize in 1-2 sentences" } ] }, "QueryItem": { "properties": { "text": { "type": "string", "title": "Text", "description": "Query text." }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Pre-computed base embedding. Skips embedder call." }, "signals": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Signals", "description": "Pre-extracted signal band-name -> text. Skips LLM extractor." }, "signal_embeddings": { "anyOf": [ { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Signal Embeddings", "description": "Pre-computed signal band-name -> vector. Skips per-band embed." }, "phases": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Phases", "description": "Pre-computed per-frequency phase angles (14-dim)." }, "rot_v3": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rot V3", "description": "Pre-computed rotation v3 vector." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat reconstruction." } }, "type": "object", "required": [ "text" ], "title": "QueryItem", "description": "Query with optional pre-computed artifacts from /v1/graph/transform.\n\nSimilar to DocumentInput but for queries. Pass pre-computed artifacts\nto skip LLM extraction and embedding for faster reranking." }, "RelationshipItem": { "properties": { "relation_type": { "type": "string", "title": "Relation Type" }, "related_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Related Item Id" }, "relationship_type": { "anyOf": [ { "$ref": "#/components/schemas/RelationshipType" }, { "type": "null" } ] }, "related_item_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Related Item Type", "description": "Legacy field - not used in processing", "default": "Memory" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "additionalProperties": false, "type": "object", "required": [ "relation_type" ], "title": "RelationshipItem", "description": "Relationship item for memory request" }, "RelationshipMatch-Input": { "properties": { "edge_type": { "type": "string", "minLength": 1, "title": "Edge Type", "description": "The relationship type to traverse (e.g., 'ASSIGNED_TO', 'BELONGS_TO')" }, "target_type": { "type": "string", "minLength": 1, "title": "Target Type", "description": "The target node type at the end of the relationship (e.g., 'Person', 'Project')" }, "target_search": { "$ref": "#/components/schemas/SearchConfig-Input", "description": "Search configuration for finding the target node. Uses the same PropertyMatch-based search as direct node search." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "title": "Direction", "description": "Direction of the relationship from the node being searched. 'outgoing': node --edge--> target (default). 'incoming': target --edge--> node.", "default": "outgoing" } }, "additionalProperties": false, "type": "object", "required": [ "edge_type", "target_type", "target_search" ], "title": "RelationshipMatch", "description": "Search for nodes via their relationships (for via_relationship in SearchConfig).\n\nEnables finding nodes based on their connections to other nodes.\nFor example: \"Find all Tasks assigned to person with email alice@example.com\"\n\n**Use Cases:**\n- Find nodes connected to a specific node\n- Navigate graph relationships during search\n- Filter nodes by their relationship targets\n\n**Example:**\n RelationshipMatch(\n edge_type=\"ASSIGNED_TO\",\n target_type=\"Person\",\n target_search=SearchConfig(properties=[\n PropertyMatch.exact(\"email\", \"alice@example.com\")\n ])\n )", "examples": [ { "name": "Find via ASSIGNED_TO", "summary": "Find nodes assigned to a specific person", "value": { "edge_type": "ASSIGNED_TO", "target_search": { "properties": [ { "name": "email", "mode": "exact", "value": "alice@example.com" } ] }, "target_type": "Person" } }, { "name": "Find via BELONGS_TO (incoming)", "summary": "Find project that tasks belong to", "value": { "direction": "incoming", "edge_type": "BELONGS_TO", "target_search": { "properties": [ { "name": "id", "mode": "exact" } ] }, "target_type": "Task" } } ] }, "RelationshipMatch-Output": { "properties": { "edge_type": { "type": "string", "minLength": 1, "title": "Edge Type", "description": "The relationship type to traverse (e.g., 'ASSIGNED_TO', 'BELONGS_TO')" }, "target_type": { "type": "string", "minLength": 1, "title": "Target Type", "description": "The target node type at the end of the relationship (e.g., 'Person', 'Project')" }, "target_search": { "$ref": "#/components/schemas/SearchConfig-Output", "description": "Search configuration for finding the target node. Uses the same PropertyMatch-based search as direct node search." }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "title": "Direction", "description": "Direction of the relationship from the node being searched. 'outgoing': node --edge--> target (default). 'incoming': target --edge--> node.", "default": "outgoing" } }, "additionalProperties": false, "type": "object", "required": [ "edge_type", "target_type", "target_search" ], "title": "RelationshipMatch", "description": "Search for nodes via their relationships (for via_relationship in SearchConfig).\n\nEnables finding nodes based on their connections to other nodes.\nFor example: \"Find all Tasks assigned to person with email alice@example.com\"\n\n**Use Cases:**\n- Find nodes connected to a specific node\n- Navigate graph relationships during search\n- Filter nodes by their relationship targets\n\n**Example:**\n RelationshipMatch(\n edge_type=\"ASSIGNED_TO\",\n target_type=\"Person\",\n target_search=SearchConfig(properties=[\n PropertyMatch.exact(\"email\", \"alice@example.com\")\n ])\n )", "examples": [ { "name": "Find via ASSIGNED_TO", "summary": "Find nodes assigned to a specific person", "value": { "edge_type": "ASSIGNED_TO", "target_search": { "properties": [ { "name": "email", "mode": "exact", "value": "alice@example.com" } ] }, "target_type": "Person" } }, { "name": "Find via BELONGS_TO (incoming)", "summary": "Find project that tasks belong to", "value": { "direction": "incoming", "edge_type": "BELONGS_TO", "target_search": { "properties": [ { "name": "id", "mode": "exact" } ] }, "target_type": "Task" } } ] }, "RelationshipSpec": { "properties": { "source": { "type": "string", "minLength": 1, "title": "Source", "description": "ID of the source node" }, "target": { "type": "string", "minLength": 1, "title": "Target", "description": "ID of the target node" }, "type": { "type": "string", "minLength": 1, "title": "Type", "description": "Relationship type (e.g., 'PURCHASED', 'WORKS_AT', 'ASSIGNED_TO')" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties", "description": "Optional properties for this relationship" } }, "additionalProperties": false, "type": "object", "required": [ "source", "target", "type" ], "title": "RelationshipSpec", "description": "Specification for a relationship in manual mode.\n\nUsed when mode='manual' to define exact relationships between nodes.", "examples": [ { "source": "txn_12345", "target": "product_latte", "type": "PURCHASED" } ] }, "RelationshipType": { "type": "string", "enum": [ "previous_memory_item_id", "all_previous_memory_items", "link_to_id" ], "title": "RelationshipType", "description": "Enum for relationship types" }, "RerankCandidate": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "description": "Text content. Required for cold path (LLM extraction + cross-encoder)." }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Base embedding. If missing and content provided, computed server-side." }, "phases": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Phases", "description": "Pre-computed phases from a prior /transform call. Enables fast path." }, "metadata_embeddings": { "anyOf": [ { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Metadata Embeddings", "description": "Pre-computed SBERT metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Enables full HCond scoring." }, "rotation_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation Embedding", "description": "Pre-computed rotation (old) embedding from holographic transform. Enables rot_v2/v3 similarity scoring and full CAESAR ensemble." }, "concat_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat Embedding", "description": "Pre-computed concat (new) embedding from holographic transform." }, "rotation_v2_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V2 Embedding", "description": "Pre-computed rotation V2 embedding from holographic transform." }, "rotation_v3_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V3 Embedding", "description": "Pre-computed rotation V3 embedding from holographic transform." }, "context_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context Metadata", "description": "Optional context metadata for cold-path LLM extraction (createdAt, sourceType, etc.)" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score", "description": "Original retrieval score (used as a signal in ensemble methods)" } }, "type": "object", "required": [ "id" ], "title": "RerankCandidate", "description": "A candidate document for reranking.\n\nAuto-detection:\n- If `phases` is provided → FAST PATH (skip LLM extraction, ~2-5ms)\n- If only `content` → COLD PATH (LLM extraction + optional cross-encoder, ~100ms)\n- Must have at least one of `content` or `phases`" }, "RerankData": { "properties": { "rankings": { "items": { "$ref": "#/components/schemas/models__holographic_models__RerankResultItem" }, "type": "array", "title": "Rankings" }, "ensemble_used": { "type": "string", "title": "Ensemble Used" }, "domain": { "type": "string", "title": "Domain" }, "timing_ms": { "type": "number", "title": "Timing Ms" }, "optimization_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Optimization Hint", "description": "Present when cold path was used. Suggests storing phases for faster reranking." }, "query_dimension_weights": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Query Dimension Weights", "description": "LLM-determined importance weights per dimension for this query (0.0-1.0). Shows how the adaptive weighting system interpreted this query's intent." } }, "type": "object", "required": [ "rankings", "ensemble_used", "domain", "timing_ms" ], "title": "RerankData" }, "RerankOptions": { "properties": { "use_cross_encoder": { "type": "boolean", "title": "Use Cross Encoder", "description": "Enable cross-encoder scoring. Requires content on candidates. Adds ~20-50ms per candidate but improves ranking quality by 3-8%%.", "default": false }, "cross_encoder_model": { "type": "string", "title": "Cross Encoder Model", "description": "Cross-encoder model name. Options: 'BAAI/bge-reranker-v2-m3' (fast, default), 'Qwen/Qwen3-Reranker-0.6B' (balanced), 'Qwen/Qwen3-Reranker-4B' (best quality).", "default": "BAAI/bge-reranker-v2-m3" }, "cross_encoder_weight": { "type": "number", "maximum": 1, "minimum": 0, "title": "Cross Encoder Weight", "description": "Weight for cross-encoder score in final blend. final = (1 - weight) * hcond + weight * cross_encoder. Default 0.3.", "default": 0.3 }, "ensemble": { "$ref": "#/components/schemas/EnsembleMethod", "description": "Ensemble method: 'auto' (recommended), 'caesar_8', or 'caesar_9'", "default": "auto" }, "scoring_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scoring Method", "description": "Specific scoring method from 160+ available (power user). Overrides ensemble." }, "return_scores": { "type": "boolean", "title": "Return Scores", "description": "Include per-method score breakdown in response", "default": true }, "include_frequency_scores": { "type": "boolean", "title": "Include Frequency Scores", "description": "Include per-frequency-field alignment scores (e.g. date: 0.92, entity: 0.45). Requires return_scores=true to take effect.", "default": false }, "frequency_filters": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Frequency Filters", "description": "Filter candidates by minimum per-frequency-field score. Keys are field names (e.g. 'date', 'entity'), values are min scores [0, 1]." } }, "type": "object", "title": "RerankOptions", "description": "Options for the rerank endpoint." }, "RerankingConfig": { "properties": { "reranking_enabled": { "type": "boolean", "title": "Reranking Enabled", "description": "When false, results stay in cosine order (same as provider=none).", "default": true }, "reranking_provider": { "$ref": "#/components/schemas/RerankingProvider", "description": "Ranking provider: none (cosine), cohere, openai, papr_enhanced (graph rerank), papr_max (graph rerank + CE + EGR).", "default": "cohere" }, "reranking_model": { "type": "string", "title": "Reranking Model", "description": "Model for cohere/openai providers. Cohere: rerank-v3.5. OpenAI: gpt-5-nano, gpt-5-mini.", "default": "rerank-v3.5" }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id", "description": "Signal domain for papr_enhanced / papr_max (default general).", "default": "general" }, "signal_thresholds": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Thresholds", "description": "Min per-band scores for papr providers." }, "return_signal_scores": { "type": "boolean", "title": "Return Signal Scores", "default": false }, "return_debug": { "type": "boolean", "title": "Return Debug", "default": false }, "signal_multipliers": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers" } }, "type": "object", "title": "RerankingConfig", "description": "Ranking provider for search results (cosine candidates → ranked list).", "examples": [ { "reranking_model": "rerank-v3.5", "reranking_provider": "cohere" }, { "reranking_model": "gpt-5-nano", "reranking_provider": "openai" }, { "domain_id": "general", "reranking_provider": "papr_enhanced", "return_signal_scores": true }, { "domain_id": "cosqa", "reranking_provider": "papr_max", "return_signal_scores": true }, { "reranking_provider": "none" } ] }, "RerankingProvider": { "type": "string", "enum": [ "none", "cohere", "openai", "papr_enhanced", "papr_max" ], "title": "RerankingProvider", "description": "How to rank Qdrant cosine candidates after retrieval." }, "ResponseFormat": { "type": "string", "enum": [ "json", "toon" ], "title": "ResponseFormat", "description": "Response format options for API endpoints.\n\n- json: Standard JSON format (default)\n- toon: Token-Oriented Object Notation format for 30-60% token reduction in LLM contexts" }, "RiskLevel": { "type": "string", "enum": [ "none", "sensitive", "flagged" ], "title": "RiskLevel", "description": "Post-ingest safety assessment of memory content.\n\nAligned with Open Memory Object (OMO) standard." }, "SchemaConfigResponse": { "properties": { "dspy_model_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dspy Model Path", "description": "Path to DSPy-optimized extractor model (null = use direct LLM)" }, "llm_metadata_model": { "type": "string", "title": "Llm Metadata Model", "description": "LLM model for metadata extraction", "default": "gpt-5-mini" }, "weight_mode": { "type": "string", "title": "Weight Mode", "description": "Frequency weight mode (legacy_sparse, code_search_v2, hybrid_optimized_v2)", "default": "legacy_sparse" }, "contrast_gamma": { "type": "number", "title": "Contrast Gamma", "description": "Contrast enhancement gamma", "default": 2 }, "use_sparse_weights": { "type": "boolean", "title": "Use Sparse Weights", "description": "Enable sparse frequency weights", "default": true }, "use_complex_interference": { "type": "boolean", "title": "Use Complex Interference", "description": "Enable complex interference scoring (PDCI, SFI)", "default": true }, "use_adaptive_weights": { "type": "boolean", "title": "Use Adaptive Weights", "description": "Enable query-adaptive frequency weights", "default": true }, "cross_encoder_model": { "type": "string", "title": "Cross Encoder Model", "description": "Cross-encoder reranking model", "default": "Qwen/Qwen3-Reranker-4B" }, "cross_encoder_topk": { "type": "integer", "title": "Cross Encoder Topk", "description": "Number of candidates for cross-encoder reranking", "default": 25 }, "qdrant_topk": { "type": "integer", "title": "Qdrant Topk", "description": "Over-fetch count from Qdrant for reranking", "default": 50 }, "enable_entailment_rerank": { "type": "boolean", "title": "Enable Entailment Rerank", "description": "Enable entailment-gated reranking (EGR)", "default": true }, "default_scoring_method": { "type": "string", "title": "Default Scoring Method", "description": "Default scoring method for this schema", "default": "egr_rerank" } }, "type": "object", "title": "SchemaConfigResponse", "description": "Operational configuration for a frequency schema." }, "SchemaListResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UserGraphSchema-Output" }, "type": "array" }, { "type": "null" } ], "title": "Data" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "code": { "type": "integer", "title": "Code", "default": 200 }, "total": { "type": "integer", "title": "Total", "default": 0 } }, "type": "object", "required": [ "success" ], "title": "SchemaListResponse", "description": "Response model for listing schemas" }, "SchemaResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/UserGraphSchema-Output" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "code": { "type": "integer", "title": "Code", "default": 200 } }, "type": "object", "required": [ "success" ], "title": "SchemaResponse", "description": "Response model for schema operations" }, "SchemaScope": { "type": "string", "enum": [ "personal", "workspace", "namespace", "organization" ], "title": "SchemaScope", "description": "Schema scopes available through the API" }, "SchemaStatus": { "type": "string", "enum": [ "draft", "active", "deprecated", "archived" ], "title": "SchemaStatus" }, "SearchConfig-Input": { "properties": { "properties": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PropertyMatch" }, "type": "array" }, { "type": "null" } ], "title": "Properties", "description": "Properties to match on, in priority order (first match wins). Accepts strings (converted to exact match) or PropertyMatch objects. Use PropertyMatch with 'value' field for specific node selection." }, "via_relationship": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipMatch-Input" }, "type": "array" }, { "type": "null" } ], "title": "Via Relationship", "description": "Search for nodes via their relationships. Example: Find tasks assigned to a specific person. Each RelationshipMatch specifies edge_type, target_type, and target_search. Multiple relationship matches are ANDed together." }, "mode": { "$ref": "#/components/schemas/SearchMode", "description": "Default search mode when property doesn't specify one. 'semantic' (vector similarity), 'exact' (property match), 'fuzzy' (partial match).", "default": "semantic" }, "threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Threshold", "description": "Default similarity threshold for semantic/fuzzy matching (0.0-1.0). Used when property doesn't specify its own threshold.", "default": 0.85 } }, "additionalProperties": false, "type": "object", "title": "SearchConfig", "description": "Configuration for finding/selecting existing nodes.\n\nDefines which properties to match on and how, in priority order.\nThe first matching property wins.\n\n**String Shorthand** (simple cases - converts to exact match):\n SearchConfig(properties=[\"id\", \"email\"])\n # Equivalent to:\n SearchConfig(properties=[PropertyMatch.exact(\"id\"), PropertyMatch.exact(\"email\")])\n\n**Mixed Form** (combine strings and PropertyMatch):\n SearchConfig(properties=[\n \"id\", # String -> exact match\n PropertyMatch.semantic(\"title\", 0.9) # Full control\n ])\n\n**Full Form** (maximum control):\n SearchConfig(properties=[\n PropertyMatch(name=\"id\", mode=\"exact\"),\n PropertyMatch(name=\"title\", mode=\"semantic\", threshold=0.85)\n ])\n\n**To select a specific node by ID**:\n SearchConfig(properties=[PropertyMatch.exact(\"id\", \"TASK-123\")])", "examples": [ { "name": "Schema Level - Multiple Match Strategies", "summary": "Try exact ID first, then semantic title", "value": { "properties": [ { "name": "id", "mode": "exact" }, { "name": "title", "mode": "semantic", "threshold": 0.85 } ] } }, { "name": "Memory Level - Select Specific Node", "summary": "Use PropertyMatch with value for direct selection", "value": { "properties": [ { "name": "id", "mode": "exact", "value": "proj_123" } ] } }, { "name": "Semantic Search with Value", "summary": "Search for nodes matching a description", "value": { "properties": [ { "name": "title", "mode": "semantic", "value": "authentication bug" } ] } }, { "name": "Person Matching", "summary": "Try email first, then name", "value": { "properties": [ { "name": "email", "mode": "exact" }, { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } }, { "name": "Via Relationship - Find nodes through edges", "summary": "Find tasks via their ASSIGNED_TO relationship to Person", "value": { "via_relationship": [ { "edge_type": "ASSIGNED_TO", "target_search": { "properties": [ { "name": "email", "mode": "exact", "value": "alice@example.com" } ] }, "target_type": "Person" } ] } } ] }, "SearchConfig-Output": { "properties": { "properties": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PropertyMatch" }, "type": "array" }, { "type": "null" } ], "title": "Properties", "description": "Properties to match on, in priority order (first match wins). Accepts strings (converted to exact match) or PropertyMatch objects. Use PropertyMatch with 'value' field for specific node selection." }, "via_relationship": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipMatch-Output" }, "type": "array" }, { "type": "null" } ], "title": "Via Relationship", "description": "Search for nodes via their relationships. Example: Find tasks assigned to a specific person. Each RelationshipMatch specifies edge_type, target_type, and target_search. Multiple relationship matches are ANDed together." }, "mode": { "$ref": "#/components/schemas/SearchMode", "description": "Default search mode when property doesn't specify one. 'semantic' (vector similarity), 'exact' (property match), 'fuzzy' (partial match).", "default": "semantic" }, "threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Threshold", "description": "Default similarity threshold for semantic/fuzzy matching (0.0-1.0). Used when property doesn't specify its own threshold.", "default": 0.85 } }, "additionalProperties": false, "type": "object", "title": "SearchConfig", "description": "Configuration for finding/selecting existing nodes.\n\nDefines which properties to match on and how, in priority order.\nThe first matching property wins.\n\n**String Shorthand** (simple cases - converts to exact match):\n SearchConfig(properties=[\"id\", \"email\"])\n # Equivalent to:\n SearchConfig(properties=[PropertyMatch.exact(\"id\"), PropertyMatch.exact(\"email\")])\n\n**Mixed Form** (combine strings and PropertyMatch):\n SearchConfig(properties=[\n \"id\", # String -> exact match\n PropertyMatch.semantic(\"title\", 0.9) # Full control\n ])\n\n**Full Form** (maximum control):\n SearchConfig(properties=[\n PropertyMatch(name=\"id\", mode=\"exact\"),\n PropertyMatch(name=\"title\", mode=\"semantic\", threshold=0.85)\n ])\n\n**To select a specific node by ID**:\n SearchConfig(properties=[PropertyMatch.exact(\"id\", \"TASK-123\")])", "examples": [ { "name": "Schema Level - Multiple Match Strategies", "summary": "Try exact ID first, then semantic title", "value": { "properties": [ { "name": "id", "mode": "exact" }, { "name": "title", "mode": "semantic", "threshold": 0.85 } ] } }, { "name": "Memory Level - Select Specific Node", "summary": "Use PropertyMatch with value for direct selection", "value": { "properties": [ { "name": "id", "mode": "exact", "value": "proj_123" } ] } }, { "name": "Semantic Search with Value", "summary": "Search for nodes matching a description", "value": { "properties": [ { "name": "title", "mode": "semantic", "value": "authentication bug" } ] } }, { "name": "Person Matching", "summary": "Try email first, then name", "value": { "properties": [ { "name": "email", "mode": "exact" }, { "name": "name", "mode": "semantic", "threshold": 0.9 } ] } }, { "name": "Via Relationship - Find nodes through edges", "summary": "Find tasks via their ASSIGNED_TO relationship to Person", "value": { "via_relationship": [ { "edge_type": "ASSIGNED_TO", "target_search": { "properties": [ { "name": "email", "mode": "exact", "value": "alice@example.com" } ] }, "target_type": "Person" } ] } } ] }, "SearchMode": { "type": "string", "enum": [ "semantic", "exact", "fuzzy" ], "title": "SearchMode", "description": "Search mode for finding existing nodes." }, "SearchOverrideFilter": { "properties": { "node_type": { "type": "string", "title": "Node Type", "description": "Node type to filter (e.g., 'Person', 'Memory', 'Company')" }, "property_name": { "type": "string", "title": "Property Name", "description": "Property name to filter on (e.g., 'name', 'content', 'role')" }, "operator": { "type": "string", "title": "Operator", "description": "Filter operator: 'CONTAINS', 'EQUALS', 'STARTS_WITH', 'IN'" }, "value": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ], "title": "Value", "description": "Filter value(s). Use list for 'IN' operator." } }, "additionalProperties": false, "type": "object", "required": [ "node_type", "property_name", "operator", "value" ], "title": "SearchOverrideFilter", "description": "Property filters for search override" }, "SearchOverridePattern": { "properties": { "source_label": { "type": "string", "title": "Source Label", "description": "Source node label (e.g., 'Memory', 'Person', 'Company'). Must match schema node types." }, "relationship_type": { "type": "string", "title": "Relationship Type", "description": "Relationship type (e.g., 'ASSOCIATED_WITH', 'WORKS_FOR'). Must match schema relationship types." }, "target_label": { "type": "string", "title": "Target Label", "description": "Target node label (e.g., 'Person', 'Company', 'Project'). Must match schema node types." }, "direction": { "type": "string", "title": "Direction", "description": "Relationship direction: '->' (outgoing), '<-' (incoming), or '-' (bidirectional)", "default": "->" } }, "additionalProperties": false, "type": "object", "required": [ "source_label", "relationship_type", "target_label" ], "title": "SearchOverridePattern", "description": "Developer-specified search pattern for search override" }, "SearchOverrideSpecification": { "properties": { "pattern": { "$ref": "#/components/schemas/SearchOverridePattern", "description": "Graph pattern to search for (source)-[relationship]->(target)" }, "filters": { "items": { "$ref": "#/components/schemas/SearchOverrideFilter" }, "type": "array", "title": "Filters", "description": "Property filters to apply to the search pattern", "default": [] }, "return_properties": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Return Properties", "description": "Specific properties to return. If not specified, returns all properties." } }, "additionalProperties": false, "type": "object", "required": [ "pattern" ], "title": "SearchOverrideSpecification", "description": "Complete search override specification provided by developer", "example": { "filters": [ { "node_type": "Person", "operator": "CONTAINS", "property_name": "name", "value": "John" }, { "node_type": "Memory", "operator": "IN", "property_name": "topics", "value": [ "project", "meeting" ] } ], "pattern": { "direction": "->", "relationship_type": "ASSOCIATED_WITH", "source_label": "Memory", "target_label": "Person" }, "return_properties": [ "name", "content", "createdAt" ] } }, "SearchRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "Detailed search query describing what you're looking for. For best results, write 2-3 sentences that include specific details, context, and time frame. Examples: 'Find recurring customer complaints about API performance from the last month. Focus on issues where customers specifically mentioned timeout errors or slow response times in their conversations.' 'What are the main issues and blockers in my current projects? Focus on technical challenges and timeline impacts.' 'Find insights about team collaboration and communication patterns from recent meetings and discussions.'", "examples": [ "Show me the most critical customer pain points from my recent conversations. Focus on issues that multiple customers have mentioned and any specific feature requests or workflow improvements they've suggested.", "What are the main issues and blockers in my current projects? Focus on technical challenges and timeline impacts.", "Find insights about team collaboration and communication patterns from recent meetings and discussions." ] }, "rank_results": { "type": "boolean", "title": "Rank Results", "description": "DEPRECATED: Use 'reranking_config' instead. Whether to enable additional ranking of search results. Default is false because results are already ranked when using an LLM for search (recommended approach). Only enable this if you're not using an LLM in your search pipeline and need additional result ranking. Migration: Replace 'rank_results: true' with 'reranking_config: {reranking_enabled: true, reranking_provider: \"cohere\", reranking_model: \"rerank-v3.5\"}'", "default": false, "deprecated": true }, "enable_agentic_graph": { "type": "boolean", "title": "Enable Agentic Graph", "description": "HIGHLY RECOMMENDED: Enable agentic graph search for intelligent, context-aware results. When enabled, the system can understand ambiguous references by first identifying specific entities from your memory graph, then performing targeted searches. Examples: 'customer feedback' → identifies your customers first, then finds their specific feedback; 'project issues' → identifies your projects first, then finds related issues; 'team meeting notes' → identifies team members first, then finds meeting notes. This provides much more relevant and comprehensive results. Set to false only if you need faster, simpler keyword-based search.", "default": false }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Your application's user identifier to filter search results. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email)." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.", "deprecated": true }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Optional organization ID for multi-tenant search scoping. When provided, search is scoped to memories within this organization." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant search scoping. When provided, search is scoped to memories within this namespace." }, "schema_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Id", "description": "Optional user-defined schema ID to use for this search. If provided, this schema (plus system schema) will be used for query generation. If not provided, system will automatically select relevant schema based on query content." }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MemoryMetadata" }, { "type": "null" } ], "description": "Optional metadata filter. Any field in MemoryMetadata (including custom fields) can be used for filtering." }, "search_override": { "anyOf": [ { "$ref": "#/components/schemas/SearchOverrideSpecification" }, { "type": "null" } ], "description": "**OPTIONAL**: Override automatic search query generation with your own exact graph pattern and filters. **⚡ AUTOMATIC BY DEFAULT**: If not provided, the system automatically generates optimized Cypher queries using AI - no action required! **🎯 USE WHEN**: You want precise control over search patterns, have specific graph traversals in mind, or want to bypass AI query generation for performance. **📋 VALIDATION**: All patterns and filters must comply with your schema definitions." }, "reranking_config": { "anyOf": [ { "$ref": "#/components/schemas/RerankingConfig" }, { "type": "null" } ], "description": "Ranking provider for search results. Default: Cohere rerank-v3.5. Use provider none for cosine-only, papr_enhanced/papr_max for graph rerank." }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/MemorySearchPolicy" }, { "type": "null" } ], "description": "DEPRECATED: Use reranking_config (papr_enhanced/papr_max) instead.", "deprecated": true }, "holographic_config": { "anyOf": [ { "$ref": "#/components/schemas/HolographicConfig" }, { "type": "null" } ], "description": "DEPRECATED: Use reranking_config provider papr_enhanced or papr_max.", "deprecated": true }, "omo_filter": { "anyOf": [ { "$ref": "#/components/schemas/OMOFilter" }, { "type": "null" } ], "description": "Optional OMO (Open Memory Object) safety filter. Filter search results by consent level and/or risk level. Use this to exclude memories without proper consent or flagged content from search results." }, "search_acl": { "anyOf": [ { "$ref": "#/components/schemas/ACLConfig" }, { "type": "null" } ], "description": "Optional ACL filter for search results. Filter memories by who has access. Use entity prefixes: 'external_user:', 'namespace:', 'organization:', 'workspace:', 'role:', 'user:'. Example: search_acl={read: ['external_user:user_001', 'namespace:ns_A']} returns only memories where both user_001 and ns_A have read access. This is useful for org-level API keys that want to find memories shared across specific namespaces or users. Namespace-scoped API keys cannot bypass their namespace scope via search_acl." } }, "type": "object", "required": [ "query" ], "title": "SearchRequest", "description": "Search request parameters", "example": { "enable_agentic_graph": false, "external_user_id": "external_user_123", "query": "Find recurring customer complaints about API performance from the last month. Focus on issues that multiple customers have mentioned and any specific feature requests or workflow improvements they've suggested.", "rank_results": true }, "search_override": { "filters": [ { "node_type": "Person", "operator": "CONTAINS", "property_name": "role", "value": "customer" }, { "node_type": "Memory", "operator": "IN", "property_name": "topics", "value": [ "API", "performance", "complaints" ] } ], "pattern": { "direction": "->", "relationship_type": "ASSOCIATED_WITH", "source_label": "Memory", "target_label": "Person" }, "return_properties": [ "name", "content", "createdAt", "topics" ] } }, "SearchResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/SearchResult" }, { "type": "null" } ], "description": "Search results if successful" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" }, "search_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Id", "description": "Unique identifier for this search query, maps to QueryLog objectId in Parse Server" } }, "type": "object", "title": "SearchResponse", "example": { "code": 200, "data": { "memories": [], "nodes": [] }, "search_id": "abc123def456", "status": "success" } }, "SearchResult": { "properties": { "memories": { "items": { "$ref": "#/components/schemas/Memory" }, "type": "array", "title": "Memories" }, "nodes": { "items": { "$ref": "#/components/schemas/Node" }, "type": "array", "title": "Nodes" }, "schemas_used": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Schemas Used", "description": "List of UserGraphSchema IDs used in this response. Use GET /v1/schemas/{id} to get full schema definitions." } }, "type": "object", "required": [ "memories", "nodes" ], "title": "SearchResult", "description": "Return type for SearchResult" }, "SessionSummaryResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID of the conversation" }, "summaries": { "$ref": "#/components/schemas/ConversationSummaryResponse", "description": "Hierarchical conversation summaries" }, "ai_agent_note": { "type": "string", "title": "Ai Agent Note", "description": "Instructions for AI agents on how to search for more details about this conversation" }, "from_cache": { "type": "boolean", "title": "From Cache", "description": "Whether summaries were retrieved from cache (true) or just generated (false)" }, "message_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Count", "description": "Number of messages summarized (only present if just generated)" } }, "type": "object", "required": [ "session_id", "summaries", "ai_agent_note", "from_cache" ], "title": "SessionSummaryResponse", "description": "Response model for session summarization endpoint", "example": { "ai_agent_note": "To find more details about this conversation, search memories with metadata filter: sessionId='session_123'", "from_cache": true, "session_id": "session_123", "summaries": { "last_updated": "2024-01-15T10:31:00Z", "long_term": "Product planning and strategy conversation focused on Q4 roadmap development and execution.", "medium_term": "Ongoing product planning discussion for Q4, covering objectives, timelines, and resource allocation.", "short_term": "User requested help planning Q4 product roadmap. Assistant offered to help identify key objectives.", "topics": [ "product planning", "Q4 roadmap", "objectives", "strategy" ] } } }, "SignalField": { "properties": { "name": { "type": "string", "title": "Name", "description": "Snake_case signal identifier." }, "description": { "type": "string", "title": "Description", "description": "Human prompt used by extractor." }, "weight": { "type": "number", "title": "Weight", "description": "Relative weight in the fusion.", "default": 1 }, "frequency_hz": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Frequency Hz", "description": "Hz band mapping (0.1 … 70.0). Auto-assigned if omitted." }, "type": { "type": "string", "enum": [ "enum", "text", "numeric", "date", "boolean", "multi_value_text" ], "title": "Type", "description": "Extraction / phase type for this signal.", "default": "text" }, "allowed_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Values", "description": "For type='enum': allowed vocabulary." }, "required": { "type": "boolean", "title": "Required", "description": "Warn when missing at extract time.", "default": false } }, "type": "object", "required": [ "name", "description" ], "title": "SignalField" }, "SyncTiersRequest": { "properties": { "max_tier0": { "type": "integer", "maximum": 2000, "minimum": 0, "title": "Max Tier0", "description": "Max Tier 0 items (goals/OKRs/use-cases)", "default": 300 }, "max_tier1": { "type": "integer", "maximum": 5000, "minimum": 0, "title": "Max Tier1", "description": "Max Tier 1 items (hot memories)", "default": 1000 }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "Optional workspace id to scope tiers" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "Optional internal user ID to filter tiers by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence." }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Optional external user ID to filter tiers by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence." }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Optional organization ID for multi-tenant scoping. When provided, tiers are scoped to memories within this organization." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant scoping. When provided, tiers are scoped to memories within this namespace." }, "include_embeddings": { "type": "boolean", "title": "Include Embeddings", "description": "Include embeddings in the response. Format controlled by embedding_format parameter.", "default": false }, "embedding_format": { "$ref": "#/components/schemas/EmbeddingFormat", "description": "Embedding format: 'int8' (quantized, 4x smaller, default for efficiency), 'float32' (full precision, recommended for CoreML/ANE fp16 models). Only applies to Tier1; Tier0 always uses float32 when embeddings are included.", "default": "int8" }, "embed_model": { "type": "string", "title": "Embed Model", "description": "Embedding model hint: 'sbert' or 'bigbird' or 'Qwen4B'", "default": "Qwen4B" }, "embed_limit": { "type": "integer", "maximum": 1000, "minimum": 0, "title": "Embed Limit", "description": "Max items to embed per tier to control latency", "default": 200 } }, "type": "object", "title": "SyncTiersRequest", "description": "Request model for sync tiers endpoint", "example": { "embed_limit": 200, "embed_model": "sbert", "external_user_id": "external_user_abc", "include_embeddings": false, "max_tier0": 300, "max_tier1": 1000, "user_id": "internal_user_123", "workspace_id": "workspace_123" } }, "SyncTiersResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "tier0": { "items": { "$ref": "#/components/schemas/Memory" }, "type": "array", "title": "Tier0", "description": "Tier 0 items (goals/OKRs/use-cases)" }, "tier1": { "items": { "$ref": "#/components/schemas/Memory" }, "type": "array", "title": "Tier1", "description": "Tier 1 items (hot memories)" }, "transitions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Transitions", "description": "Transition items between tiers" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for pagination" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether there are more items available", "default": false }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" } }, "type": "object", "title": "SyncTiersResponse", "description": "Response model for sync tiers endpoint", "example": { "code": 200, "has_more": false, "status": "success", "tier0": [ { "content": "Improve API performance", "id": "goal_123", "metadata": { "class": "goal", "sourceType": "papr" }, "topics": [ "performance", "api" ], "type": "goal" } ], "tier1": [ { "content": "Customer complained about slow API response times", "id": "memory_456", "metadata": { "sourceType": "papr" }, "topics": [ "customer", "api", "performance" ], "type": "text" } ], "transitions": [] } }, "SystemUpdateStatus": { "properties": { "pinecone": { "type": "boolean", "title": "Pinecone", "default": false }, "neo4j": { "type": "boolean", "title": "Neo4J", "default": false }, "parse": { "type": "boolean", "title": "Parse", "default": false } }, "type": "object", "title": "SystemUpdateStatus", "description": "Status of update operation for each system" }, "TelemetryEvent": { "properties": { "event_name": { "type": "string", "title": "Event Name", "description": "Event name (e.g., 'memory_created', 'search_performed')" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties", "description": "Event properties (will be anonymized)" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "Anonymous user ID (hashed)" }, "timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Timestamp", "description": "Event timestamp (Unix epoch in milliseconds)" } }, "type": "object", "required": [ "event_name" ], "title": "TelemetryEvent", "description": "Single telemetry event" }, "TelemetryRequest": { "properties": { "events": { "items": { "$ref": "#/components/schemas/TelemetryEvent" }, "type": "array", "title": "Events", "description": "List of telemetry events to track" }, "anonymous_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anonymous Id", "description": "Anonymous session ID" } }, "type": "object", "required": [ "events" ], "title": "TelemetryRequest", "description": "Request body for telemetry endpoint" }, "TelemetryResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether the events were successfully processed" }, "events_received": { "type": "integer", "title": "Events Received", "description": "Number of events received" }, "events_processed": { "type": "integer", "title": "Events Processed", "description": "Number of events successfully processed" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Optional message" } }, "type": "object", "required": [ "success", "events_received", "events_processed" ], "title": "TelemetryResponse", "description": "Response from telemetry endpoint" }, "TextMode": { "type": "string", "enum": [ "replace", "append", "merge" ], "title": "TextMode", "description": "How to handle text/description property updates." }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token", "description": "OAuth2 access token" }, "token_type": { "type": "string", "title": "Token Type", "description": "Token type", "default": "Bearer" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Token expiration time in seconds" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token", "description": "Refresh token for getting new access tokens" }, "scope": { "type": "string", "title": "Scope", "description": "OAuth2 scopes granted" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "User ID from Auth0" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Additional message or status" } }, "type": "object", "required": [ "access_token", "expires_in", "scope" ], "title": "TokenResponse", "description": "Response model for OAuth2 token endpoint" }, "TransformData": { "properties": { "base": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Base", "description": "Original embedding echoed back" }, "rotation_v1": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V1", "description": "Rotation V1 transform (same dims as input)" }, "rotation_v2": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V2", "description": "Rotation V2 transform (same dims as input)" }, "rotation_v3": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Rotation V3", "description": "Rotation V3 transform (recommended for search, same dims as input)" }, "concat": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Concat", "description": "Concatenation transform (input_dims + 196)" }, "phases": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Phases", "description": "14 raw phase values for on-device reconstruction and fast-path rerank" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "LLM-extracted metadata keyed by frequency field name" }, "metadata_embeddings": { "anyOf": [ { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Metadata Embeddings", "description": "Per-frequency metadata embeddings" }, "dimension_weights": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Dimension Weights", "description": "Adaptive per-field weights (queries only, when is_query=true). Pass to /rerank as query_dimension_weights to skip recomputation." }, "domain": { "type": "string", "title": "Domain", "description": "Domain used for this transform" }, "frequency_schema_id": { "type": "string", "title": "Frequency Schema Id", "description": "Exact frequency schema ID used" }, "base_dim": { "type": "integer", "title": "Base Dim", "description": "Input embedding dimensionality" }, "timing_ms": { "type": "number", "title": "Timing Ms", "description": "Server-side processing time in milliseconds" } }, "type": "object", "required": [ "domain", "frequency_schema_id", "base_dim", "timing_ms" ], "title": "TransformData", "description": "Inner data for transform response — only requested fields are populated.", "example": { "base_dim": 2560, "domain": "biomedical", "frequency_schema_id": "biomedical:scifact:2.0.0", "metadata": { "category": "biomarker", "entity": "troponin" }, "phases": [ 0.42, 0.78, 0.15 ], "rotation_v3": [ 0.12, -0.34 ], "timing_ms": 142.3 } }, "TransformEmbeddingMode": { "type": "string", "enum": [ "none", "auto", "manual" ], "title": "TransformEmbeddingMode" }, "TransformEmbeddingPolicy": { "properties": { "mode": { "$ref": "#/components/schemas/TransformEmbeddingMode", "description": "none=base embed only; auto=run graph transform; manual=BYO signals", "default": "auto" }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id", "description": "Signal domain id or shorthand (e.g. cosqa)" }, "signals": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Signals", "description": "BYO band text values when mode=manual" } }, "type": "object", "title": "TransformEmbeddingPolicy" }, "UpdateMemoryItem": { "properties": { "objectId": { "type": "string", "title": "Objectid" }, "memoryId": { "type": "string", "title": "Memoryid" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "default": "" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "memoryChunkIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Memorychunkids", "default": [ [] ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MemoryMetadata" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "objectId", "memoryId", "updatedAt" ], "title": "UpdateMemoryItem", "description": "Model for a single updated memory item" }, "UpdateMemoryRequest": { "properties": { "policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryAddPolicy" }, { "type": "null" } ], "description": "Unified processing policy: transform_embedding, graph, consent, risk, acl." }, "memory_policy": { "anyOf": [ { "$ref": "#/components/schemas/MemoryPolicy" }, { "type": "null" } ], "description": "DEPRECATED: Use 'policy' instead. Legacy graph + OMO policy. Use mode='auto' (LLM extraction, constraints applied if provided) or 'manual' (exact nodes). Includes consent, risk, and ACL settings. If schema_id is set, schema's memory_policy is used as defaults.", "deprecated": true }, "link_to": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Link To", "description": "DEPRECATED: Use policy.graph.link_to instead. Shorthand DSL for node/edge constraints (same as node_constraints, compact syntax). Expands and merges into memory_policy.node_constraints and edge_constraints at resolve time. Default create is upsert; use dict form with create='lookup' (or legacy 'never') for link-only. Formats: - String: 'Task:title' (semantic match on Task.title, upsert by default) - List: ['Task:title', 'Person:email'] (multiple constraints) - Dict: {'Task:title': {'set': {...}, 'create': 'lookup'}} (full options) Syntax: - Node: 'Type:property', 'Type:prop=value' (exact), 'Type:prop~value' (semantic) - Edge: 'Source->EDGE->Target:property' (arrow syntax) - Via: 'Type.via(EDGE->Target:prop)' (relationship traversal) - Special: '$this', '$previous', '$context:N' Example lookup-only: {'SecurityPolicy:name': {'create': 'lookup'}}", "deprecated": true }, "graph_generation": { "anyOf": [ { "$ref": "#/components/schemas/GraphGeneration" }, { "type": "null" } ], "description": "DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration. If both memory_policy and graph_generation are provided, memory_policy takes precedence.", "deprecated": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "description": "The new content of the memory item" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/MemoryType" }, { "type": "null" } ], "description": "Content type of the memory item" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MemoryMetadata" }, { "type": "null" } ], "description": "Updated metadata for Neo4J and Pinecone" }, "context": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ContextItem" }, "type": "array" }, { "type": "null" } ], "title": "Context", "description": "Updated context for the memory item" }, "relationships_json": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelationshipItem" }, "type": "array" }, { "type": "null" } ], "title": "Relationships Json", "description": "Updated relationships for Graph DB (neo4J)" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Optional organization ID for multi-tenant memory scoping. When provided, update is scoped to memories within this organization." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID for multi-tenant memory scoping. When provided, update is scoped to memories within this namespace." } }, "additionalProperties": false, "type": "object", "title": "UpdateMemoryRequest", "description": "Request model for updating an existing memory.\n\nInherits memory_policy from SchemaSpecificationMixin for controlling:\n- Graph generation mode (auto, manual)\n- Node constraints for LLM extraction (applied in auto mode when present)\n- OMO safety standards (consent, risk, ACL)", "example": { "content": "Updated meeting notes from the product planning session", "context": [ { "content": "Let's update the Q2 product roadmap", "role": "user" }, { "content": "I'll help you update the roadmap. What changes would you like to make?", "role": "assistant" } ], "metadata": { "emoji tags": "📊,💡,📝,✨", "emotion tags": "focused, productive, satisfied", "hierarchical structures": "Business/Planning/Product/Updates", "topics": "product, planning, updates" }, "relationships_json": [ { "metadata": { "relevance": "high" }, "related_item_id": "previous_memory_item_id", "related_item_type": "TextMemoryItem", "relation_type": "updates" } ], "type": "text" } }, "UpdateMemoryResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code", "default": 200 }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'", "default": "success" }, "memory_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UpdateMemoryItem" }, "type": "array" }, { "type": "null" } ], "title": "Memory Items", "description": "List of updated memory items if successful" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Additional error details or context" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Status message" }, "status_obj": { "anyOf": [ { "$ref": "#/components/schemas/SystemUpdateStatus" }, { "type": "null" } ], "description": "System update status (pinecone, neo4j, parse)" } }, "additionalProperties": false, "type": "object", "title": "UpdateMemoryResponse", "description": "Unified response model for update_memory API endpoint (success or error)." }, "UpdateNamespaceRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Updated namespace name" }, "environment_type": { "anyOf": [ { "$ref": "#/components/schemas/EnvironmentType" }, { "type": "null" } ], "description": "Updated environment type" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether this namespace is active" }, "rate_limits": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Rate Limits", "description": "Updated rate limits (None values inherit from organization)" }, "default_policy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Default Policy", "description": "Default memory policy for add/search when request omits policy." } }, "type": "object", "title": "UpdateNamespaceRequest", "description": "Request body for PUT /v1/namespace/{namespace_id}", "example": { "environment_type": "staging", "is_active": true, "name": "acme-staging" } }, "UpdateSessionRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "New title for the session" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata to merge with existing session metadata" } }, "type": "object", "title": "UpdateSessionRequest", "description": "Request model for updating session properties" }, "UpdateUserRequest": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/UserType" }, { "type": "null" } ] } }, "type": "object", "title": "UpdateUserRequest", "description": "Request model for updating a user", "example": { "email": "updated.user@example.com", "external_id": "updated_user_123", "metadata": { "name": "Updated User", "preferences": { "theme": "light" } }, "type": "developerUser" } }, "UserGraphSchema-Input": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description" }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "title": "Version", "default": "1.0.0" }, "user_id": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Id" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Workspace Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization ID this schema belongs to. Accepts legacy 'organization' alias." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace ID this schema belongs to. Accepts legacy 'namespace' alias." }, "organization": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Organization", "description": "DEPRECATED: Use 'organization_id' instead. Accepts Parse pointer or objectId.", "deprecated": true }, "namespace": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Namespace", "description": "DEPRECATED: Use 'namespace_id' instead. Accepts Parse pointer or objectId.", "deprecated": true }, "node_types": { "additionalProperties": { "$ref": "#/components/schemas/UserNodeType-Input" }, "type": "object", "title": "Node Types", "description": "Custom node types (max 10 per schema)" }, "relationship_types": { "additionalProperties": { "$ref": "#/components/schemas/UserRelationshipType-Input" }, "type": "object", "title": "Relationship Types", "description": "Custom relationship types (max 20 per schema)" }, "memory_policy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Memory Policy", "description": "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": { "$ref": "#/components/schemas/SchemaStatus", "default": "draft" }, "scope": { "$ref": "#/components/schemas/SchemaScope", "default": "organization" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "read_access": { "items": { "type": "string" }, "type": "array", "title": "Read Access" }, "write_access": { "items": { "type": "string" }, "type": "array", "title": "Write Access" }, "usage_count": { "type": "integer", "title": "Usage Count", "default": 0 }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "UserGraphSchema", "description": "Complete user-defined graph schema" }, "UserGraphSchema-Output": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description" }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "title": "Version", "default": "1.0.0" }, "user_id": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Id" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Workspace Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization ID this schema belongs to. Accepts legacy 'organization' alias." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace ID this schema belongs to. Accepts legacy 'namespace' alias." }, "organization": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Organization", "description": "DEPRECATED: Use 'organization_id' instead. Accepts Parse pointer or objectId.", "deprecated": true }, "namespace": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Namespace", "description": "DEPRECATED: Use 'namespace_id' instead. Accepts Parse pointer or objectId.", "deprecated": true }, "node_types": { "additionalProperties": { "$ref": "#/components/schemas/UserNodeType-Output" }, "type": "object", "title": "Node Types", "description": "Custom node types (max 10 per schema)" }, "relationship_types": { "additionalProperties": { "$ref": "#/components/schemas/UserRelationshipType-Output" }, "type": "object", "title": "Relationship Types", "description": "Custom relationship types (max 20 per schema)" }, "memory_policy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Memory Policy", "description": "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": { "$ref": "#/components/schemas/SchemaStatus", "default": "draft" }, "scope": { "$ref": "#/components/schemas/SchemaScope", "default": "organization" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "read_access": { "items": { "type": "string" }, "type": "array", "title": "Read Access" }, "write_access": { "items": { "type": "string" }, "type": "array", "title": "Write Access" }, "usage_count": { "type": "integer", "title": "Usage Count", "default": 0 }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "UserGraphSchema", "description": "Complete user-defined graph schema" }, "UserInfoResponse": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "Internal user ID" }, "sessionToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessiontoken", "description": "Session token for API access" }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Imageurl", "description": "User profile image URL" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Displayname", "description": "User display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "User email address" }, "message": { "type": "string", "title": "Message", "description": "Authentication status message", "default": "You are authenticated!" } }, "type": "object", "required": [ "user_id" ], "title": "UserInfoResponse", "description": "Response model for /me endpoint" }, "UserListResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code" }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UserResponse" }, "type": "array" }, { "type": "null" } ], "title": "Data" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details" } }, "type": "object", "required": [ "code", "status" ], "title": "UserListResponse", "example": { "code": 200, "data": [ { "created_at": "2024-03-20T10:00:00.000Z", "email": "user1@example.com", "external_id": "user123", "metadata": { "name": "John Doe", "preferences": { "theme": "dark" } }, "updated_at": "2024-03-20T10:00:00.000Z", "user_id": "abc123" } ], "page": 1, "page_size": 10, "status": "success", "total": 1 } }, "UserMemoryCategory": { "type": "string", "enum": [ "preference", "task", "goal", "fact", "context" ], "title": "UserMemoryCategory", "description": "Memory categories for user messages" }, "UserNodeType-Input": { "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "title": "Name" }, "label": { "type": "string", "title": "Label" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/PropertyDefinition" }, "type": "object", "title": "Properties", "description": "Node properties (max 10 per node type)" }, "required_properties": { "items": { "type": "string" }, "type": "array", "title": "Required Properties" }, "unique_identifiers": { "items": { "type": "string" }, "type": "array", "title": "Unique Identifiers", "description": "DEPRECATED: Use 'constraint.search.properties' instead. Properties that uniquely identify this node type. Example: ['name', 'email'] for Customer nodes." }, "constraint": { "anyOf": [ { "$ref": "#/components/schemas/NodeConstraint-Input" }, { "type": "null" } ], "description": "Default constraint for this node type. Defines: 1. search.properties - unique identifiers and how to match them 2. create - 'upsert' (create if not found) or 'lookup' (controlled vocabulary) 3. when - conditional application with logical operators 4. set - default property values. Note: node_type is implicit (taken from this UserNodeType.name)." }, "resolution_policy": { "type": "string", "enum": [ "upsert", "lookup" ], "title": "Resolution Policy", "description": "Shorthand for constraint.create. 'upsert': Create if not found (default). 'lookup': Only link to existing nodes (controlled vocabulary). Equivalent to @upsert/@lookup decorators. If constraint is also provided, resolution_policy will set constraint.create accordingly.", "default": "upsert" }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use resolution_policy='lookup' instead. Shorthand for constraint with create='lookup'. When True, only links to existing nodes (controlled vocabulary). Equivalent to @lookup decorator. If constraint is also provided, link_only=True will override constraint.create to 'lookup'.", "default": false }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "default": "#3498db" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" } }, "additionalProperties": false, "type": "object", "required": [ "name", "label" ], "title": "UserNodeType", "description": "User-defined node type with optional inline constraint.\n\nThe `constraint` field allows defining default matching/creation behavior\ndirectly within the node type definition. This replaces the need to put\nconstraints only in memory_policy.node_constraints.\n\nSchema-level constraints:\n- `node_type` is implicit (taken from parent UserNodeType.name)\n- Defines default matching strategy via `search.properties`\n- Can be overridden per-memory via memory_policy.node_constraints\n\nExample:\n UserNodeType(\n name=\"Task\",\n label=\"Task\",\n properties={\n \"id\": PropertyDefinition(type=\"string\"),\n \"title\": PropertyDefinition(type=\"string\", required=True)\n },\n constraint=NodeConstraint(\n search=SearchConfig(properties=[\n PropertyMatch(name=\"id\", mode=\"exact\"),\n PropertyMatch(name=\"title\", mode=\"semantic\", threshold=0.85)\n ]),\n create=\"auto\"\n )\n )" }, "UserNodeType-Output": { "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "title": "Name" }, "label": { "type": "string", "title": "Label" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/PropertyDefinition" }, "type": "object", "title": "Properties", "description": "Node properties (max 10 per node type)" }, "required_properties": { "items": { "type": "string" }, "type": "array", "title": "Required Properties" }, "unique_identifiers": { "items": { "type": "string" }, "type": "array", "title": "Unique Identifiers", "description": "DEPRECATED: Use 'constraint.search.properties' instead. Properties that uniquely identify this node type. Example: ['name', 'email'] for Customer nodes." }, "constraint": { "anyOf": [ { "$ref": "#/components/schemas/NodeConstraint-Output" }, { "type": "null" } ], "description": "Default constraint for this node type. Defines: 1. search.properties - unique identifiers and how to match them 2. create - 'upsert' (create if not found) or 'lookup' (controlled vocabulary) 3. when - conditional application with logical operators 4. set - default property values. Note: node_type is implicit (taken from this UserNodeType.name)." }, "resolution_policy": { "type": "string", "enum": [ "upsert", "lookup" ], "title": "Resolution Policy", "description": "Shorthand for constraint.create. 'upsert': Create if not found (default). 'lookup': Only link to existing nodes (controlled vocabulary). Equivalent to @upsert/@lookup decorators. If constraint is also provided, resolution_policy will set constraint.create accordingly.", "default": "upsert" }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use resolution_policy='lookup' instead. Shorthand for constraint with create='lookup'. When True, only links to existing nodes (controlled vocabulary). Equivalent to @lookup decorator. If constraint is also provided, link_only=True will override constraint.create to 'lookup'.", "default": false }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "default": "#3498db" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" } }, "additionalProperties": false, "type": "object", "required": [ "name", "label" ], "title": "UserNodeType", "description": "User-defined node type with optional inline constraint.\n\nThe `constraint` field allows defining default matching/creation behavior\ndirectly within the node type definition. This replaces the need to put\nconstraints only in memory_policy.node_constraints.\n\nSchema-level constraints:\n- `node_type` is implicit (taken from parent UserNodeType.name)\n- Defines default matching strategy via `search.properties`\n- Can be overridden per-memory via memory_policy.node_constraints\n\nExample:\n UserNodeType(\n name=\"Task\",\n label=\"Task\",\n properties={\n \"id\": PropertyDefinition(type=\"string\"),\n \"title\": PropertyDefinition(type=\"string\", required=True)\n },\n constraint=NodeConstraint(\n search=SearchConfig(properties=[\n PropertyMatch(name=\"id\", mode=\"exact\"),\n PropertyMatch(name=\"title\", mode=\"semantic\", threshold=0.85)\n ]),\n create=\"auto\"\n )\n )" }, "UserRelationshipType-Input": { "properties": { "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "title": "Name" }, "label": { "type": "string", "title": "Label" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/PropertyDefinition" }, "type": "object", "title": "Properties" }, "allowed_source_types": { "items": { "type": "string" }, "type": "array", "title": "Allowed Source Types" }, "allowed_target_types": { "items": { "type": "string" }, "type": "array", "title": "Allowed Target Types" }, "cardinality": { "type": "string", "enum": [ "one-to-one", "one-to-many", "many-to-many" ], "title": "Cardinality", "default": "many-to-many" }, "constraint": { "anyOf": [ { "$ref": "#/components/schemas/EdgeConstraint-Input" }, { "type": "null" } ], "description": "Default constraint for this relationship type. Defines: 1. search.properties - how to find existing target nodes 2. create - 'upsert' (create if not found) or 'lookup' (controlled vocabulary) 3. when - conditional application with logical operators 4. set - default edge property values. Note: edge_type is implicit (taken from this UserRelationshipType.name)." }, "resolution_policy": { "type": "string", "enum": [ "upsert", "lookup" ], "title": "Resolution Policy", "description": "Shorthand for constraint.create. 'upsert': Create target if not found (default). 'lookup': Only link to existing targets (controlled vocabulary). Equivalent to @upsert/@lookup decorators. If constraint is also provided, resolution_policy will set constraint.create accordingly.", "default": "upsert" }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use resolution_policy='lookup' instead. Shorthand for constraint with create='lookup'. When True, only links to existing target nodes (controlled vocabulary). Equivalent to @lookup decorator. If constraint is also provided, link_only=True will override constraint.create to 'lookup'.", "default": false }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "default": "#e74c3c" } }, "additionalProperties": false, "type": "object", "required": [ "name", "label", "allowed_source_types", "allowed_target_types" ], "title": "UserRelationshipType", "description": "User-defined relationship type with optional inline constraint.\n\nThe `constraint` field allows defining default matching/creation behavior\ndirectly within the relationship type definition. This mirrors the pattern\nused in UserNodeType.constraint for nodes.\n\nSchema-level edge constraints:\n- `edge_type` is implicit (taken from parent UserRelationshipType.name)\n- Defines default target node matching strategy via `search.properties`\n- Can be overridden per-memory via memory_policy.edge_constraints\n\nExample:\n UserRelationshipType(\n name=\"MITIGATES\",\n label=\"Mitigates\",\n allowed_source_types=[\"SecurityBehavior\"],\n allowed_target_types=[\"TacticDef\"],\n constraint=EdgeConstraint(\n search=SearchConfig(properties=[\n PropertyMatch(name=\"name\", mode=\"semantic\", threshold=0.90)\n ]),\n create=\"never\" # Controlled vocabulary - only link to existing targets\n )\n )" }, "UserRelationshipType-Output": { "properties": { "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "title": "Name" }, "label": { "type": "string", "title": "Label" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/PropertyDefinition" }, "type": "object", "title": "Properties" }, "allowed_source_types": { "items": { "type": "string" }, "type": "array", "title": "Allowed Source Types" }, "allowed_target_types": { "items": { "type": "string" }, "type": "array", "title": "Allowed Target Types" }, "cardinality": { "type": "string", "enum": [ "one-to-one", "one-to-many", "many-to-many" ], "title": "Cardinality", "default": "many-to-many" }, "constraint": { "anyOf": [ { "$ref": "#/components/schemas/EdgeConstraint-Output" }, { "type": "null" } ], "description": "Default constraint for this relationship type. Defines: 1. search.properties - how to find existing target nodes 2. create - 'upsert' (create if not found) or 'lookup' (controlled vocabulary) 3. when - conditional application with logical operators 4. set - default edge property values. Note: edge_type is implicit (taken from this UserRelationshipType.name)." }, "resolution_policy": { "type": "string", "enum": [ "upsert", "lookup" ], "title": "Resolution Policy", "description": "Shorthand for constraint.create. 'upsert': Create target if not found (default). 'lookup': Only link to existing targets (controlled vocabulary). Equivalent to @upsert/@lookup decorators. If constraint is also provided, resolution_policy will set constraint.create accordingly.", "default": "upsert" }, "link_only": { "type": "boolean", "title": "Link Only", "description": "DEPRECATED: Use resolution_policy='lookup' instead. Shorthand for constraint with create='lookup'. When True, only links to existing target nodes (controlled vocabulary). Equivalent to @lookup decorator. If constraint is also provided, link_only=True will override constraint.create to 'lookup'.", "default": false }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "default": "#e74c3c" } }, "additionalProperties": false, "type": "object", "required": [ "name", "label", "allowed_source_types", "allowed_target_types" ], "title": "UserRelationshipType", "description": "User-defined relationship type with optional inline constraint.\n\nThe `constraint` field allows defining default matching/creation behavior\ndirectly within the relationship type definition. This mirrors the pattern\nused in UserNodeType.constraint for nodes.\n\nSchema-level edge constraints:\n- `edge_type` is implicit (taken from parent UserRelationshipType.name)\n- Defines default target node matching strategy via `search.properties`\n- Can be overridden per-memory via memory_policy.edge_constraints\n\nExample:\n UserRelationshipType(\n name=\"MITIGATES\",\n label=\"Mitigates\",\n allowed_source_types=[\"SecurityBehavior\"],\n allowed_target_types=[\"TacticDef\"],\n constraint=EdgeConstraint(\n search=SearchConfig(properties=[\n PropertyMatch(name=\"name\", mode=\"semantic\", threshold=0.90)\n ]),\n create=\"never\" # Controlled vocabulary - only link to existing targets\n )\n )" }, "UserResponse": { "properties": { "code": { "type": "integer", "title": "Code", "description": "HTTP status code" }, "status": { "type": "string", "title": "Status", "description": "'success' or 'error'" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details" } }, "type": "object", "required": [ "code", "status" ], "title": "UserResponse", "description": "Response model for user operations", "example": { "code": 200, "created_at": "2024-03-20T10:00:00.000Z", "email": "user@example.com", "external_id": "user123", "metadata": { "name": "John Doe", "preferences": { "theme": "dark" } }, "status": "success", "updated_at": "2024-03-20T10:00:00.000Z", "user_id": "abc123" } }, "UserType": { "type": "string", "enum": [ "developerUser", "user", "agent" ], "title": "UserType" }, "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" }, "VectorPolicy": { "properties": { "mode": { "$ref": "#/components/schemas/VectorRetrievalMode", "description": "fast=cosine; enhanced=graph rerank enhanced; max=graph rerank max", "default": "enhanced" }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id" }, "signal_thresholds": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Thresholds", "description": "Min per-band scores; maps to graph rerank signal_filters" }, "return_signal_scores": { "type": "boolean", "title": "Return Signal Scores", "default": false }, "return_debug": { "type": "boolean", "title": "Return Debug", "default": false }, "signal_multipliers": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "type": "object" }, { "type": "null" } ], "title": "Signal Multipliers" } }, "type": "object", "title": "VectorPolicy" }, "VectorRetrievalMode": { "type": "string", "enum": [ "fast", "enhanced", "max" ], "title": "VectorRetrievalMode" }, "models__holographic_models__RerankResultItem": { "properties": { "id": { "type": "string", "title": "Id" }, "rank": { "type": "integer", "title": "Rank" }, "score": { "type": "number", "title": "Score", "description": "Ensemble score" }, "original_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Original Score", "description": "Original retrieval score if provided" }, "path": { "type": "string", "title": "Path", "description": "'fast' (phases provided) or 'cold' (content-only)" }, "scores": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Scores", "description": "Per-method score breakdown (if return_scores=true)" }, "frequency_scores": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Frequency Scores", "description": "Per-frequency-field alignment scores (when options.include_frequency_scores=true)." } }, "type": "object", "required": [ "id", "rank", "score", "path" ], "title": "RerankResultItem", "description": "Single ranked result." }, "services__holographic_embedding__graph__models__RerankResultItem": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Position in the input documents array." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Doc id if input was an object, else null." }, "relevance_score": { "type": "number", "title": "Relevance Score", "description": "Final ranked score — the real similarity from the CAESAR-8 routed method." }, "score_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Score Method", "description": "Which method CAESAR-8 routed to for this query (e.g. 'caesar7', 'baseline_rerank'). Tells you what kind of signal `relevance_score` reflects." }, "signal_scores": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Scores", "description": "Stable, documented signals (only if return_signal_scores=true). Always includes `base_sim` and `caesar8_score`. On `enhanced` method, also includes `rot_k{32,128,256,512}_sim` low-rank rotation variants." }, "signal_scores_by_band": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Signal Scores By Band", "description": "Per-band signal similarities, keyed by band name (e.g. {'causal_agent': 0.83, 'causal_verb': 0.91}). Only set if return_signal_scores=true and the pipeline computed gated SFI." }, "debug_scores": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Debug Scores", "description": "Kitchen-sink: every *_sim signal computed by the pipeline. Only if return_debug=true. NOT a stable contract — keys may change." }, "document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentInput" }, { "type": "null" } ], "description": "Echoed input doc (only if return_documents=true)." } }, "type": "object", "required": [ "index", "relevance_score" ], "title": "RerankResultItem" } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token (JWT) from Auth0 OAuth2 or similar" }, "X-Session-Token": { "type": "apiKey", "in": "header", "name": "X-Session-Token", "description": "Session token for authentication" }, "X-API-Key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication" }, "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://memory.papr.ai/login", "tokenUrl": "https://memory.papr.ai/token", "refreshUrl": "https://memory.papr.aitoken", "scopes": { "openid": "OpenID", "profile": "Profile access", "email": "Email access", "offline_access": "Offline access" } } } } } }, "servers": [ { "url": "https://memory.papr.ai", "description": "Production server" } ] }