{ "components": { "parameters": { "IdempotencyKey": { "description": "Opaque retry key (1-255 characters). Reuse the same key only for the exact same authenticated mutation. Most operations replay a completed 2xx response for 24 hours. Canonical memory and correction writes instead replay the same PostgreSQL-owned logical result and may report newer readiness; inspect each operation's x-hebbrix-idempotency.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } }, "schemas": { "APICallsQuota": { "description": "API call quota shape for PDF contract top-level ``api_calls`` field.", "properties": { "limit": { "title": "Limit", "type": "integer" }, "percentage": { "title": "Percentage", "type": "number" }, "remaining": { "title": "Remaining", "type": "integer" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "used", "limit", "remaining", "percentage" ], "title": "APICallsQuota", "type": "object" }, "APIKeyCreate": { "description": "API key creation schema.", "properties": { "name": { "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "APIKeyCreate", "type": "object" }, "APIKeyListItem": { "description": "API key list item schema (without full key).", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" } }, "required": [ "id", "name", "prefix", "is_active", "created_at" ], "title": "APIKeyListItem", "type": "object" }, "APIKeyResponse": { "description": "API key response schema.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "key": { "title": "Key", "type": "string" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" } }, "required": [ "id", "name", "key", "prefix", "created_at" ], "title": "APIKeyResponse", "type": "object" }, "APIKeyUsage": { "description": "Usage statistics for a specific API key.", "properties": { "api_key_id": { "title": "Api Key Id", "type": "string" }, "api_key_name": { "title": "Api Key Name", "type": "string" }, "api_key_prefix": { "title": "Api Key Prefix", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "failed_requests": { "title": "Failed Requests", "type": "integer" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "successful_requests": { "title": "Successful Requests", "type": "integer" }, "total_bytes_received": { "title": "Total Bytes Received", "type": "integer" }, "total_bytes_sent": { "title": "Total Bytes Sent", "type": "integer" }, "total_requests": { "title": "Total Requests", "type": "integer" } }, "required": [ "api_key_id", "api_key_name", "api_key_prefix", "total_requests", "successful_requests", "failed_requests", "total_bytes_sent", "total_bytes_received", "last_used_at", "created_at" ], "title": "APIKeyUsage", "type": "object" }, "AccountDeleteResponse": { "description": "Account deletion response schema.", "properties": { "deleted_at": { "format": "date-time", "title": "Deleted At", "type": "string" }, "message": { "title": "Message", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "message", "user_id", "deleted_at" ], "title": "AccountDeleteResponse", "type": "object" }, "AccountDeletionRequest": { "description": "Request for account deletion.", "properties": { "confirm_email": { "format": "email", "title": "Confirm Email", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "confirm_email" ], "title": "AccountDeletionRequest", "type": "object" }, "AccountDeletionResponse": { "description": "Response for account deletion.", "properties": { "deletion_scheduled_at": { "format": "date-time", "title": "Deletion Scheduled At", "type": "string" }, "message": { "title": "Message", "type": "string" }, "permanent_deletion_after_days": { "default": 90, "title": "Permanent Deletion After Days", "type": "integer" } }, "required": [ "message", "deletion_scheduled_at" ], "title": "AccountDeletionResponse", "type": "object" }, "AccountRestoreRequest": { "description": "Password reauthentication fallback when the old JWT has expired.", "properties": { "email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "title": "Email" }, "password": { "anyOf": [ { "maxLength": 1024, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Password" } }, "title": "AccountRestoreRequest", "type": "object" }, "AddKeyRequest": { "properties": { "api_key": { "title": "Api Key", "type": "string" } }, "required": [ "api_key" ], "title": "AddKeyRequest", "type": "object" }, "AddKeyResponse": { "properties": { "key_preview": { "title": "Key Preview", "type": "string" }, "message": { "title": "Message", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "validation_status": { "title": "Validation Status", "type": "string" } }, "required": [ "provider", "key_preview", "validation_status", "message" ], "title": "AddKeyResponse", "type": "object" }, "AddToWorkingMemoryRequest": { "description": "Request model for adding to working memory.", "properties": { "content": { "maxLength": 100000, "minLength": 1, "title": "Content", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "role": { "pattern": "^(user|assistant|system)$", "title": "Role", "type": "string" }, "session_id": { "maxLength": 200, "minLength": 1, "title": "Session Id", "type": "string" } }, "required": [ "session_id", "role", "content" ], "title": "AddToWorkingMemoryRequest", "type": "object" }, "AdvancedSearchRequest": { "description": "Advanced search request with additional filtering and boosting options.\n\n2026-05-11: prior version of this schema had NO validation on `query`,\n`limit`, `min_score`, or `search_type` \u2014 accepted empty/whitespace queries,\nnegative/huge limits, out-of-range scores, and silently-fell-back search\ntypes. Now mirrors `SearchRequest`'s bounds.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "boost_important": { "default": false, "title": "Boost Important", "type": "boolean" }, "boost_recent": { "default": false, "title": "Boost Recent", "type": "boolean" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "date_range_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date Range End" }, "date_range_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date Range Start" }, "entity_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Entity Filter" }, "filters": { "additionalProperties": true, "default": {}, "title": "Filters", "type": "object" }, "include_explanations": { "default": true, "title": "Include Explanations", "type": "boolean" }, "limit": { "default": 10, "description": "Number of results (1-100)", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "min_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Minimum relevance score (0.0\u20131.0)", "title": "Min Score" }, "query": { "description": "Search query (cannot be empty)", "minLength": 1, "title": "Query", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "search_type": { "default": "hybrid", "enum": [ "hybrid", "vector", "bm25", "graph" ], "title": "Search Type", "type": "string" }, "temporal_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Temporal Mode" }, "use_enhanced": { "default": true, "title": "Use Enhanced", "type": "boolean" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "query" ], "title": "AdvancedSearchRequest", "type": "object" }, "AgentContext": { "description": "Optional context for agent requests.", "properties": { "app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Application identifier", "title": "App Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by collection", "title": "Collection Id" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Namespace for isolation", "title": "Namespace" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Session for conversation continuity", "title": "Session Id" } }, "title": "AgentContext", "type": "object" }, "AgentRequest": { "description": "Unified agent request schema.\n\nSupports action-based dispatching where AI agents specify\nthe action name and parameters explicitly.", "examples": [ { "action": "search_memories", "params": { "limit": 5, "query": "Python programming" } }, { "action": "create_memory", "params": { "content": "User is learning React" } }, { "action": "chat", "params": { "messages": [ { "content": "What do I know about AI?", "role": "user" } ], "session_id": "session-123" } } ], "properties": { "action": { "description": "Canonical action name such as search_memories or create_memory. The ergonomic aliases recall and remember are also accepted.", "title": "Action", "type": "string" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/AgentContext" }, { "type": "null" } ], "description": "Optional context (collection, session, etc.)" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Parameters for the action", "title": "Params" } }, "required": [ "action" ], "title": "AgentRequest", "type": "object" }, "AgentResponse": { "description": "Unified agent response schema.\n\nProvides standardized output format with:\n- Success/failure status\n- Action taken\n- Result data\n- Explanation for AI agents\n- Suggested follow-ups\n- Performance metadata", "example": { "action_taken": "search_memories", "explanation": "Found 1 memory matching 'Python'", "metadata": { "processing_time_ms": 45, "tokens_used": 0 }, "result": { "memories": [ { "content": "User likes Python", "id": "mem-1", "score": 0.95 } ], "total": 1 }, "success": true, "suggested_actions": [ { "action": "get_memory", "description": "Get full details of a specific memory", "params": { "memory_id": "mem-1" } } ] }, "properties": { "action_taken": { "description": "The action that was executed", "title": "Action Taken", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if failed", "title": "Error" }, "explanation": { "description": "Human-readable explanation", "title": "Explanation", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Performance and usage metadata", "title": "Metadata", "type": "object" }, "result": { "anyOf": [ {}, { "type": "null" } ], "description": "Action result data", "title": "Result" }, "success": { "description": "Whether the action succeeded", "title": "Success", "type": "boolean" }, "suggested_actions": { "description": "Suggested follow-up actions", "items": { "$ref": "#/components/schemas/SuggestedAction" }, "title": "Suggested Actions", "type": "array" } }, "required": [ "success", "action_taken", "explanation" ], "title": "AgentResponse", "type": "object" }, "AgentSignupRequest": { "description": "Optional self-reported attribution + optional proof-of-work solution.", "properties": { "agent_caller": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Self-reported calling agent, e.g. 'claude-code', 'cursor'", "title": "Agent Caller" }, "challenge": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Proof-of-work challenge from POST /agent-signup/challenge", "title": "Challenge" }, "nonce": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Solved PoW nonce. A valid PoW skips the per-IP/subnet caps.", "title": "Nonce" } }, "title": "AgentSignupRequest", "type": "object" }, "AgentSignupResponse": { "properties": { "agent_id": { "title": "Agent Id", "type": "string" }, "api_key": { "title": "Api Key", "type": "string" }, "claim_command": { "default": "hebbrix-mcp claim --email ", "title": "Claim Command", "type": "string" }, "collection_id": { "title": "Collection Id", "type": "string" }, "docs": { "default": "https://www.hebbrix.com/docs", "title": "Docs", "type": "string" }, "expires_at": { "title": "Expires At", "type": "string" }, "limits": { "additionalProperties": true, "title": "Limits", "type": "object" }, "tier": { "default": "shadow", "title": "Tier", "type": "string" } }, "required": [ "api_key", "agent_id", "collection_id", "limits", "expires_at" ], "title": "AgentSignupResponse", "type": "object" }, "AllConsentsResponse": { "description": "All current consent statuses.", "properties": { "consents": { "items": { "$ref": "#/components/schemas/ConsentStatusResponse" }, "title": "Consents", "type": "array" } }, "required": [ "consents" ], "title": "AllConsentsResponse", "type": "object" }, "AnomalyResponse": { "description": "Anomaly response schema.", "properties": { "anomaly_type": { "title": "Anomaly Type", "type": "string" }, "confidence": { "title": "Confidence", "type": "number" }, "description": { "title": "Description", "type": "string" }, "detected_at": { "format": "date-time", "title": "Detected At", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "severity": { "title": "Severity", "type": "string" } }, "required": [ "anomaly_type", "severity", "confidence", "detected_at", "description", "metadata" ], "title": "AnomalyResponse", "type": "object" }, "AskQuestionRequest": { "description": "Request to ask a question using your stored memories as context.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "conversation_history": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SimpleMessage" }, "type": "array" }, { "type": "null" } ], "default": [], "title": "Conversation History" }, "memory_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Memory Limit" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "openai", "title": "Provider" }, "question": { "title": "Question", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "user_context": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "User Context" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "question" ], "title": "AskQuestionRequest", "type": "object" }, "AskQuestionResponse": { "description": "Response with answer and sources.", "properties": { "answer": { "title": "Answer", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "sources": { "items": { "$ref": "#/components/schemas/Source" }, "title": "Sources", "type": "array" } }, "required": [ "answer", "sources", "metadata" ], "title": "AskQuestionResponse", "type": "object" }, "BackupCodesResponse": { "description": "Regenerated backup codes response.", "properties": { "backup_codes": { "items": { "type": "string" }, "title": "Backup Codes", "type": "array" }, "backup_codes_count": { "title": "Backup Codes Count", "type": "integer" }, "message": { "default": "New backup codes generated. Previous codes are now invalid.", "title": "Message", "type": "string" }, "warning": { "default": "Save these backup codes in a secure location. They will not be shown again.", "title": "Warning", "type": "string" } }, "required": [ "backup_codes", "backup_codes_count" ], "title": "BackupCodesResponse", "type": "object" }, "BatchMemoryCreate": { "description": "Batch memory creation schema for high-throughput ingestion.\n\nAccepts up to 100 memories per request for 10-20x faster ingestion.\nAll memories go to the same collection.", "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "app_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "App ID for collection resolution", "title": "App Id" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Target collection ID", "title": "Collection Id" }, "memories": { "description": "List of memories to create (max 100 per batch)", "items": { "$ref": "#/components/schemas/BatchMemoryItem" }, "maxItems": 100, "minItems": 1, "title": "Memories", "type": "array" }, "namespace": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Namespace for collection resolution", "title": "Namespace" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Default end-user scope for all items (persisted as Memory.end_user_id). Aliases: end_user_id, enduser_id.", "title": "User Id" }, "wait_for_index": { "default": false, "description": "Read-after-write preference. When true, the server first attempts a bounded synchronous observation. A fully searchable batch returns 201; a durably committed batch still converging returns 202 with memory IDs, outbox event ID, Location/status_url, and Retry-After. Official SDKs poll that receipt to their caller-configured deadline.", "title": "Wait For Index", "type": "boolean" } }, "required": [ "memories" ], "title": "BatchMemoryCreate", "type": "object" }, "BatchMemoryItem": { "description": "Single memory item for batch ingestion.\n\ncollection_id may be given here per-item OR once at the top level of the\nbatch request. All memories in a batch must resolve to the SAME collection.\n(Per-item collection_id used to be silently dropped, which misfiled the whole\nbatch into the default collection \u2014 it is now honored.)", "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Target collection (must match the other items / top-level)", "title": "Collection Id" }, "content": { "description": "Memory content", "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "importance": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Importance (auto-calculated if not provided)", "title": "Importance" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "tags": { "anyOf": [ { "items": { "maxLength": 128, "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "description": "Tags for categorization", "title": "Tags" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "End-user scope (persisted as Memory.end_user_id). Aliases: end_user_id, enduser_id. Falls back to the batch-level user_id.", "title": "User Id" } }, "required": [ "content" ], "title": "BatchMemoryItem", "type": "object" }, "BatchMemoryItemResult": { "description": "Per-item result for a batch create: the id and its indexing status.", "properties": { "id": { "title": "Id", "type": "string" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" }, "processing_status": { "default": "pending", "description": "pending \u2192 processing \u2192 completed (searchable) | failed. Poll GET /v1/memories/{id} for live status.", "title": "Processing Status", "type": "string" } }, "required": [ "id" ], "title": "BatchMemoryItemResult", "type": "object" }, "BatchMemoryResponse": { "description": "Response for batch memory creation.", "properties": { "accepted": { "default": true, "title": "Accepted", "type": "boolean" }, "created": { "title": "Created", "type": "integer" }, "durable": { "default": true, "title": "Durable", "type": "boolean" }, "errors": { "default": [], "items": { "type": "string" }, "title": "Errors", "type": "array" }, "failed": { "title": "Failed", "type": "integer" }, "idempotency_replay": { "default": false, "title": "Idempotency Replay", "type": "boolean" }, "memory_ids": { "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Durable batch indexing event used for retry correlation.", "title": "Outbox Event Id" }, "processing_status": { "description": "completed only when every accepted item is searchable; processing means the durable outbox is still converging.", "title": "Processing Status", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "results": { "default": [], "items": { "$ref": "#/components/schemas/BatchMemoryItemResult" }, "title": "Results", "type": "array" }, "searchable": { "description": "True only when every accepted item is end-to-end searchable.", "title": "Searchable", "type": "boolean" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readiness URL for the first item; every result also carries its id.", "title": "Status Url" } }, "required": [ "created", "failed", "memory_ids", "processing_status", "searchable" ], "title": "BatchMemoryResponse", "type": "object" }, "BatchURLImportRequest": { "description": "Batch URL import request.", "properties": { "collection_id": { "anyOf": [ { "maxLength": 36, "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "create_memories": { "default": true, "title": "Create Memories", "type": "boolean" }, "urls": { "items": { "maxLength": 2048, "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Urls", "type": "array" } }, "required": [ "urls" ], "title": "BatchURLImportRequest", "type": "object" }, "BillingInterval": { "enum": [ "monthly", "yearly" ], "title": "BillingInterval", "type": "string" }, "BillingPortalResponse": { "description": "Billing portal session response.", "properties": { "portal_url": { "title": "Portal Url", "type": "string" } }, "required": [ "portal_url" ], "title": "BillingPortalResponse", "type": "object" }, "BillingTransparencyResponse": { "description": "Complete billing transparency response.\n\nShows users exactly what they're being charged, like Gemini does.\nThis is critical for building trust with users.", "properties": { "actual_tokens_this_month": { "description": "Actual tokens consumed this month (before multipliers)", "title": "Actual Tokens This Month", "type": "integer" }, "billed_tokens_this_month": { "description": "Total billed tokens this month (after multipliers)", "title": "Billed Tokens This Month", "type": "integer" }, "cost_per_million_tokens": { "description": "Your effective rate per 1M tokens in USD", "title": "Cost Per Million Tokens", "type": "number" }, "estimated_spend_usd": { "description": "Estimated spend this month in USD", "title": "Estimated Spend Usd", "type": "number" }, "models_available": { "description": "Available models and their multipliers", "items": { "$ref": "#/components/schemas/ModelCost" }, "title": "Models Available", "type": "array" }, "tier": { "description": "Current subscription tier", "title": "Tier", "type": "string" }, "tier_display_name": { "description": "Human-readable tier name", "title": "Tier Display Name", "type": "string" }, "tier_price": { "description": "Monthly subscription price", "title": "Tier Price", "type": "string" }, "token_quota": { "$ref": "#/components/schemas/TokenQuotaInfo", "description": "Detailed token quota information" }, "usage_by_model": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "description": "Token usage breakdown by model", "title": "Usage By Model", "type": "object" } }, "required": [ "tier", "tier_display_name", "tier_price", "token_quota", "cost_per_million_tokens", "models_available", "billed_tokens_this_month", "actual_tokens_this_month", "estimated_spend_usd", "usage_by_model" ], "title": "BillingTransparencyResponse", "type": "object" }, "Body_login_oauth_v1_auth_token_post": { "properties": { "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "grant_type": { "anyOf": [ { "pattern": "password", "type": "string" }, { "type": "null" } ], "title": "Grant Type" }, "password": { "title": "Password", "type": "string" }, "scope": { "default": "", "title": "Scope", "type": "string" }, "username": { "title": "Username", "type": "string" } }, "required": [ "username", "password" ], "title": "Body_login_oauth_v1_auth_token_post", "type": "object" }, "Body_upload_document_v1_documents_upload_post": { "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "file": { "format": "binary", "title": "File", "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tags" } }, "required": [ "file" ], "title": "Body_upload_document_v1_documents_upload_post", "type": "object" }, "Body_upload_documents_batch_v1_documents_upload_batch_post": { "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "files": { "items": { "format": "binary", "type": "string" }, "title": "Files", "type": "array" } }, "required": [ "files" ], "title": "Body_upload_documents_batch_v1_documents_upload_batch_post", "type": "object" }, "Body_upload_media_v1_media_upload_post": { "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "file": { "format": "binary", "title": "File", "type": "string" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" } }, "required": [ "file" ], "title": "Body_upload_media_v1_media_upload_post", "type": "object" }, "BulkQualityResponse": { "description": "Response for bulk quality assessment.", "properties": { "assessments": { "items": { "$ref": "#/components/schemas/QualityAssessment" }, "title": "Assessments", "type": "array" }, "summary": { "additionalProperties": true, "title": "Summary", "type": "object" }, "total_assessed": { "title": "Total Assessed", "type": "integer" } }, "required": [ "assessments", "summary", "total_assessed" ], "title": "BulkQualityResponse", "type": "object" }, "CanaryDeploymentRequest": { "description": "Request model for canary deployment.", "properties": { "baseline_checkpoint_path": { "title": "Baseline Checkpoint Path", "type": "string" }, "canary_checkpoint_path": { "title": "Canary Checkpoint Path", "type": "string" } }, "required": [ "canary_checkpoint_path", "baseline_checkpoint_path" ], "title": "CanaryDeploymentRequest", "type": "object" }, "CancelRequest": { "description": "Subscription cancellation request.", "properties": { "cancel_immediately": { "default": false, "description": "If true, cancel now. If false, cancel at period end.", "title": "Cancel Immediately", "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cancellation reason", "title": "Reason" } }, "title": "CancelRequest", "type": "object" }, "CandidateAction": { "additionalProperties": false, "properties": { "action_key": { "maxLength": 160, "minLength": 1, "title": "Action Key", "type": "string" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "features": { "additionalProperties": true, "title": "Features", "type": "object" } }, "required": [ "action_key" ], "title": "CandidateAction", "type": "object" }, "ChangePasswordRequest": { "description": "Request schema for authenticated password change.", "properties": { "current_password": { "title": "Current Password", "type": "string" }, "new_password": { "title": "New Password", "type": "string" } }, "required": [ "current_password", "new_password" ], "title": "ChangePasswordRequest", "type": "object" }, "ChangePasswordResponse": { "description": "Response schema for password change.", "properties": { "message": { "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "ChangePasswordResponse", "type": "object" }, "ChangePlanRequest": { "description": "Plan change request.", "properties": { "new_plan_id": { "description": "New plan ID to switch to", "title": "New Plan Id", "type": "string" }, "prorate": { "default": true, "description": "Whether to prorate charges", "title": "Prorate", "type": "boolean" } }, "required": [ "new_plan_id" ], "title": "ChangePlanRequest", "type": "object" }, "ChatChoice": { "description": "Chat completion choice.", "properties": { "finish_reason": { "title": "Finish Reason", "type": "string" }, "index": { "title": "Index", "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" } }, "required": [ "index", "message", "finish_reason" ], "title": "ChatChoice", "type": "object" }, "ChatCompletionRequest": { "description": "Chat completion request (OpenAI-compatible with Hebbrix extensions).", "example": { "collection_id": "col_abc123", "features": { "learning": true, "memory": true, "personalization": true, "user_profile": true }, "messages": [ { "content": "What's my name?", "role": "user" } ], "model": "gpt-5-mini", "session_id": "user_123" }, "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent ID to scope memory retrieval", "title": "Agent Id" }, "collection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias for collection_id", "title": "Collection" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection ID to scope memory retrieval", "title": "Collection Id" }, "features": { "$ref": "#/components/schemas/ChatFeatures", "description": "Feature flags" }, "grounding": { "default": "soft", "description": "Memory claim-grounding policy. soft preserves structurally eligible ranked candidates with an explicit ungrounded receipt; strict admits only verified evidence; off bypasses the claim filter.", "enum": [ "off", "soft", "strict" ], "title": "Grounding", "type": "string" }, "max_tokens": { "anyOf": [ { "maximum": 32768.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Maximum completion tokens to generate (1-32768)", "title": "Max Tokens" }, "memory_limit": { "default": 10, "description": "Max memories to inject into the prompt. Accepts aliases top_k / max_memories / memory_top_k.", "maximum": 50.0, "minimum": 1.0, "title": "Memory Limit", "type": "integer" }, "messages": { "description": "Conversation messages", "items": { "$ref": "#/components/schemas/ChatMessage" }, "title": "Messages", "type": "array" }, "min_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Optional retrieval relevance floor (0-1). Lower = broader recall. Accepts aliases memory_min_score / min_relevance.", "title": "Min Score" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LLM model to use. Defaults to user's preferred model or tier default.", "title": "Model" }, "n": { "anyOf": [ { "maximum": 4.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "default": 1, "description": "Number of completions", "title": "N" }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Allow the model to emit parallel tool calls", "title": "Parallel Tool Calls" }, "prompt_strategy": { "default": "default", "description": "Prompt template strategy", "title": "Prompt Strategy", "type": "string" }, "recall_mode": { "default": false, "description": "Enable the wider, facet-oriented retrieval plan without changing the chat response or generation contract.", "title": "Recall Mode", "type": "boolean" }, "response_format": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "OpenAI-compatible text or JSON response format", "title": "Response Format" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Run ID to scope memory retrieval", "title": "Run Id" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set 'all' to explicitly search the entire account across all end-users.", "title": "Scope" }, "search_type": { "default": "hybrid", "description": "Memory retrieval strategy used by this completion.", "enum": [ "hybrid", "vector", "bm25", "graph" ], "title": "Search Type", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Session identifier for conversation tracking. Auto-generated if not provided.", "title": "Session Id" }, "stop": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Stop sequences", "title": "Stop" }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Stream responses", "title": "Stream" }, "temperature": { "anyOf": [ { "maximum": 2.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 0.7, "description": "Sampling temperature", "title": "Temperature" }, "tool_choice": { "anyOf": [ {}, { "type": "null" } ], "description": "OpenAI-compatible tool selection policy", "title": "Tool Choice" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "OpenAI-compatible tools available to the model", "title": "Tools" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": 1.0, "description": "Nucleus sampling parameter", "title": "Top P" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user ID to scope memory retrieval (multi-tenant isolation)", "title": "User Id" } }, "required": [ "messages" ], "title": "ChatCompletionRequest", "type": "object" }, "ChatCompletionResponse": { "description": "Chat completion response (OpenAI-compatible with Hebbrix extensions).", "properties": { "abstain_recommended": { "default": false, "title": "Abstain Recommended", "type": "boolean" }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/backend__api__v1__endpoints__chat__BillingInfo" }, { "type": "null" } ], "description": "Token billing details - shows exactly what you're charged" }, "choices": { "items": { "$ref": "#/components/schemas/ChatChoice" }, "title": "Choices", "type": "array" }, "created": { "title": "Created", "type": "integer" }, "evidence_claims": { "items": { "additionalProperties": true, "type": "object" }, "title": "Evidence Claims", "type": "array" }, "evidence_ids": { "items": { "type": "string" }, "title": "Evidence Ids", "type": "array" }, "grounding": { "additionalProperties": true, "title": "Grounding", "type": "object" }, "id": { "title": "Id", "type": "string" }, "memory_context": { "$ref": "#/components/schemas/MemoryContext" }, "model": { "title": "Model", "type": "string" }, "no_match": { "default": false, "title": "No Match", "type": "boolean" }, "object": { "default": "chat.completion", "title": "Object", "type": "string" }, "query_confidence": { "default": 0.0, "maximum": 1.0, "minimum": 0.0, "title": "Query Confidence", "type": "number" }, "safety_contract_version": { "default": "search-safety-v1", "title": "Safety Contract Version", "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "id", "created", "model", "choices", "usage", "memory_context" ], "title": "ChatCompletionResponse", "type": "object" }, "ChatFeatures": { "description": "Feature flags for chat completions.", "properties": { "deep_personalization": { "default": true, "description": "Use adaptive learning analytics (NEW)", "title": "Deep Personalization", "type": "boolean" }, "learning": { "default": true, "description": "Log trajectories for RL training", "title": "Learning", "type": "boolean" }, "memory": { "default": true, "description": "Auto-retrieve relevant memories", "title": "Memory", "type": "boolean" }, "personalization": { "default": true, "description": "Use RL-optimized strategies", "title": "Personalization", "type": "boolean" }, "user_profile": { "default": true, "description": "Inject user profile context", "title": "User Profile", "type": "boolean" } }, "title": "ChatFeatures", "type": "object" }, "ChatMessage": { "description": "Chat message in OpenAI format.", "properties": { "content": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "description": "Message content", "title": "Content" }, "function_call": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Function call (deprecated)", "title": "Function Call" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Participant name", "title": "Name" }, "role": { "description": "Message role: system, user, assistant, tool", "title": "Role", "type": "string" }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tool call ID for responses", "title": "Tool Call Id" }, "tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Tool calls", "title": "Tool Calls" } }, "required": [ "role" ], "title": "ChatMessage", "type": "object" }, "CheckErrorRequest": { "description": "Request to check if error was seen before.", "properties": { "error_message": { "description": "The error message", "title": "Error Message", "type": "string" }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Type of error (e.g., TypeError, SyntaxError)", "title": "Error Type" }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File where error occurred", "title": "File Path" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Programming language", "title": "Language" }, "stack_trace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full stack trace", "title": "Stack Trace" } }, "required": [ "error_message" ], "title": "CheckErrorRequest", "type": "object" }, "CheckoutRequest": { "description": "Checkout session request.", "properties": { "cancel_url": { "description": "URL to redirect if checkout is canceled", "title": "Cancel Url", "type": "string" }, "plan_id": { "description": "Plan ID to subscribe to", "maxLength": 100, "minLength": 1, "title": "Plan Id", "type": "string" }, "success_url": { "description": "URL to redirect after successful payment", "title": "Success Url", "type": "string" } }, "required": [ "plan_id", "success_url", "cancel_url" ], "title": "CheckoutRequest", "type": "object" }, "CheckoutResponse": { "description": "Checkout session response.", "properties": { "checkout_url": { "title": "Checkout Url", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" } }, "required": [ "session_id", "checkout_url" ], "title": "CheckoutResponse", "type": "object" }, "CheckpointRequest": { "description": "Request model for checkpoint operations.", "properties": { "checkpoint_path": { "title": "Checkpoint Path", "type": "string" } }, "required": [ "checkpoint_path" ], "title": "CheckpointRequest", "type": "object" }, "ClaimRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "ClaimRequest", "type": "object" }, "ClaimVerifyRequest": { "properties": { "code": { "maxLength": 6, "minLength": 6, "title": "Code", "type": "string" } }, "required": [ "code" ], "title": "ClaimVerifyRequest", "type": "object" }, "CodingHistoryRequest": { "description": "Request for coding history.", "properties": { "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by file path", "title": "File Path" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by language", "title": "Language" }, "limit": { "default": 10, "description": "Max number of results", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "task_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by task type", "title": "Task Type" } }, "title": "CodingHistoryRequest", "type": "object" }, "CollectionCreate": { "description": "Collection creation schema.\n\n``name`` is bounded to 255 chars because the underlying column is\n``String(255)``. Without this bound, overlong input surfaces as a\nPostgres StringDataRightTruncation error \u2192 HTTP 500.", "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "CollectionCreate", "type": "object" }, "CollectionEnsureRequest": { "description": "Request to ensure a collection exists.", "properties": { "collection_id": { "description": "The collection ID to ensure exists", "title": "Collection Id", "type": "string" }, "fallback_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Name for the collection if it needs to be created", "title": "Fallback Name" } }, "required": [ "collection_id" ], "title": "CollectionEnsureRequest", "type": "object" }, "CollectionResponse": { "description": "Collection response schema.", "properties": { "created": { "default": true, "title": "Created", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "memory_count": { "title": "Memory Count", "type": "integer" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "name": { "title": "Name", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "description", "is_active", "memory_count", "metadata", "created_at", "updated_at" ], "title": "CollectionResponse", "type": "object" }, "CollectionUpdate": { "description": "Collection update schema.", "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "require_user_id": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Require User Id" } }, "title": "CollectionUpdate", "type": "object" }, "ConfidenceResponse": { "description": "Response from the confidence scoring endpoint.", "properties": { "answer_confidence": { "description": "Groundedness of an answer (same value as confidence)", "maximum": 1.0, "minimum": 0.0, "title": "Answer Confidence", "type": "number" }, "as_of": { "description": "UTC ISO timestamp when this confidence was computed", "title": "As Of", "type": "string" }, "confidence": { "description": "Confidence score [0, 1]", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "constraint_conflict": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Set when the proposed action violates a stored numeric bound or categorical prohibition. Numeric conflicts include query_value, threshold, direction, and unit; categorical conflicts include matched_terms and matched_categories. recommended_action is do_not_act.", "title": "Constraint Conflict" }, "contributing_corrections": { "description": "Relevant corrections that influenced the recommendation, with polarity (suppress|assert)", "items": { "additionalProperties": true, "type": "object" }, "title": "Contributing Corrections", "type": "array" }, "corrections_exist": { "description": "True if the user has active corrections", "title": "Corrections Exist", "type": "boolean" }, "decision_count": { "default": 0, "description": "Number of logged decisions relevant to this query", "title": "Decision Count", "type": "integer" }, "decision_evidence_strength": { "default": 0.0, "description": "How much evaluated outcome evidence exists; zero means none.", "maximum": 1.0, "minimum": 0.0, "title": "Decision Evidence Strength", "type": "number" }, "decision_outcome_summary": { "additionalProperties": { "type": "integer" }, "description": "Counts of relevant decision outcomes, e.g. {'success': 3, 'failure': 1}", "title": "Decision Outcome Summary", "type": "object" }, "decision_success_lower_bound": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "95% Wilson lower confidence bound for the relevant decision success rate. This is the conservative outcome signal used by the autonomy gate.", "title": "Decision Success Lower Bound" }, "decision_success_rate": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Observed success rate for relevant evaluated decisions.", "title": "Decision Success Rate" }, "grounding_estimate": { "description": "Top-scored memory relevance estimate", "maximum": 1.0, "minimum": 0.0, "title": "Grounding Estimate", "type": "number" }, "index_possibly_stale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Reviewer BT1: true when no conflict fired, nothing was grounded, AND the collection has a write in the last 60s \u2014 the vector index may be lagging, so a rule-based safety check could be incomplete. Retry in a few seconds before trusting a 'clear' result for a consequential action.", "title": "Index Possibly Stale" }, "last_correction_age_days": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Age of the most-recent active correction in days", "title": "Last Correction Age Days" }, "pending_writes": { "default": 0, "description": "Memories in scope still indexing (processing_status != completed). Grounding does not yet reflect these. Poll until 0 for a final value.", "title": "Pending Writes", "type": "integer" }, "reasoning": { "description": "Human-readable explanation of the score", "title": "Reasoning", "type": "string" }, "recommendation": { "description": "Safety-aware action: act_autonomously | proceed_with_caution | ask_user | do_not_act (alias of recommended_action)", "title": "Recommendation", "type": "string" }, "recommended_action": { "description": "act_autonomously | proceed_with_caution | ask_user | do_not_act. do_not_act is returned when a relevant correction or decision history forbids the proposed action, regardless of groundedness.", "title": "Recommended Action", "type": "string" }, "safety_reasons": { "description": "Machine-readable reasons that constrained the recommendation.", "items": { "type": "string" }, "title": "Safety Reasons", "type": "array" }, "supporting_memories": { "description": "Number of memories retrieved for this query", "title": "Supporting Memories", "type": "integer" } }, "required": [ "confidence", "answer_confidence", "recommendation", "recommended_action", "supporting_memories", "corrections_exist", "grounding_estimate", "reasoning", "as_of" ], "title": "ConfidenceResponse", "type": "object" }, "ConsentHistoryResponse": { "description": "Consent history list.", "properties": { "history": { "items": { "$ref": "#/components/schemas/ConsentResponse" }, "title": "History", "type": "array" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "history", "total_count" ], "title": "ConsentHistoryResponse", "type": "object" }, "ConsentRecordedResponse": { "description": "Response after recording consent.", "properties": { "consent_type": { "title": "Consent Type", "type": "string" }, "granted": { "title": "Granted", "type": "boolean" }, "message": { "title": "Message", "type": "string" }, "recorded_at": { "format": "date-time", "title": "Recorded At", "type": "string" } }, "required": [ "message", "consent_type", "granted", "recorded_at" ], "title": "ConsentRecordedResponse", "type": "object" }, "ConsentRequest": { "description": "Request to record consent.", "properties": { "consent_type": { "$ref": "#/components/schemas/ConsentTypeEnum" }, "granted": { "title": "Granted", "type": "boolean" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "consent_type", "granted" ], "title": "ConsentRequest", "type": "object" }, "ConsentResponse": { "description": "Response for a single consent record.", "properties": { "consent_type": { "title": "Consent Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "granted": { "title": "Granted", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "id", "consent_type", "granted", "created_at" ], "title": "ConsentResponse", "type": "object" }, "ConsentStatusResponse": { "description": "Current consent status.", "properties": { "consent_type": { "title": "Consent Type", "type": "string" }, "granted": { "title": "Granted", "type": "boolean" }, "last_updated": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Updated" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "consent_type", "granted" ], "title": "ConsentStatusResponse", "type": "object" }, "ConsentTypeEnum": { "description": "Consent types for API.", "enum": [ "terms_of_service", "privacy_policy", "marketing_email", "marketing_sms", "data_processing", "third_party_sharing", "analytics", "cookies" ], "title": "ConsentTypeEnum", "type": "string" }, "ConsentWithdrawResponse": { "description": "Response after withdrawing consent.", "properties": { "consent_type": { "title": "Consent Type", "type": "string" }, "message": { "title": "Message", "type": "string" }, "withdrawn_at": { "format": "date-time", "title": "Withdrawn At", "type": "string" } }, "required": [ "message", "consent_type", "withdrawn_at" ], "title": "ConsentWithdrawResponse", "type": "object" }, "ConsolidateMemoriesRequest": { "description": "Request model for consolidating memories.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "memory_ids": { "items": { "type": "string" }, "title": "Memory Ids", "type": "array" } }, "required": [ "memory_ids", "collection_id" ], "title": "ConsolidateMemoriesRequest", "type": "object" }, "ConsolidateResponse": { "description": "Durable working-memory consolidation and search-readiness receipt.", "properties": { "memories_created": { "title": "Memories Created", "type": "integer" }, "memory_ids": { "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "message": { "title": "Message", "type": "string" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "processing_status": { "title": "Processing Status", "type": "string" }, "searchable": { "title": "Searchable", "type": "boolean" }, "session_id": { "title": "Session Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Url" } }, "required": [ "status", "session_id", "memories_created", "memory_ids", "processing_status", "searchable", "message" ], "title": "ConsolidateResponse", "type": "object" }, "ConversationStarter": { "description": "A single conversation starter.", "properties": { "context": { "description": "Context about why this starter was generated", "title": "Context", "type": "string" }, "question": { "description": "The conversation starter question", "title": "Question", "type": "string" }, "type": { "description": "Generation type (llm_generated, template_based, generic)", "title": "Type", "type": "string" } }, "required": [ "question", "context", "type" ], "title": "ConversationStarter", "type": "object" }, "CorrectionCreate": { "additionalProperties": false, "description": "Request body for creating a new correction.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent ID this correction targets (if any)", "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection to scope this correction to (multi-tenant isolation)", "title": "Collection Id" }, "confidence": { "default": 1.0, "description": "Confidence in this correction (0\u20131)", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Additional context describing when this correction applies", "title": "Context" }, "corrected_content": { "description": "The corrected / preferred content", "minLength": 1, "title": "Corrected Content", "type": "string" }, "correction_type": { "default": "preference", "description": "Type of correction: preference, factual, or procedural (default preference).", "enum": [ "preference", "factual", "procedural" ], "title": "Correction Type", "type": "string" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Memory ID this correction is linked to (if any)", "title": "Memory Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Arbitrary structured metadata about the correction", "title": "Metadata" }, "original_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The original (incorrect) content being corrected", "title": "Original Content" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user ID to scope this correction to (multi-tenant isolation)", "title": "User Id" } }, "required": [ "corrected_content" ], "title": "CorrectionCreate", "type": "object" }, "CorrectionResponse": { "description": "Response schema for a single correction.", "properties": { "account_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "attempts": { "default": 0, "title": "Attempts", "type": "integer" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "confidence": { "title": "Confidence", "type": "number" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context" }, "corrected_content": { "title": "Corrected Content", "type": "string" }, "correction_type": { "title": "Correction Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" }, "next_retry_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Next Retry At" }, "original_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Content" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "processing_status": { "default": "completed", "description": "Durable lifecycle state: accepted, processing, completed, or failed. Completed means the canonical dense and sparse search indexes are visible.", "title": "Processing Status", "type": "string" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retry After Seconds" }, "searchable": { "default": true, "title": "Searchable", "type": "boolean" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Url" }, "times_applied": { "title": "Times Applied", "type": "number" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "id", "agent_id", "memory_id", "original_content", "corrected_content", "correction_type", "context", "confidence", "times_applied", "is_active", "created_at", "updated_at" ], "title": "CorrectionResponse", "type": "object" }, "CreateEntityRequest": { "description": "Request to create an entity.", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "name": { "title": "Name", "type": "string" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties" }, "type": { "title": "Type", "type": "string" } }, "required": [ "name", "type" ], "title": "CreateEntityRequest", "type": "object" }, "CreateProcedureRequest": { "description": "Request model for creating a procedure.", "properties": { "action": { "additionalProperties": true, "title": "Action", "type": "object" }, "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "condition": { "additionalProperties": true, "title": "Condition", "type": "object" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "name", "condition", "action" ], "title": "CreateProcedureRequest", "type": "object" }, "CreateRelationshipRequest": { "description": "Request to create a relationship between entities.\n\nAccepts both PDF-contract short names (``source``/``target``/``type``)\nand legacy long names (``source_entity``/``target_entity``/``relationship_type``).", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "confidence": { "default": 0.5, "description": "Confidence in this relationship (0.0\u20131.0). Edge weight in visualizations.", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties" }, "relationship_type": { "description": "KNOWS, WORKS_AT, LOCATED_IN, etc.", "title": "Relationship Type", "type": "string" }, "source_entity": { "title": "Source Entity", "type": "string" }, "target_entity": { "title": "Target Entity", "type": "string" } }, "required": [ "source_entity", "target_entity", "relationship_type" ], "title": "CreateRelationshipRequest", "type": "object" }, "CreateTicketRequest": { "properties": { "category": { "default": "general", "enum": [ "bug", "feature_request", "billing", "account", "general" ], "title": "Category", "type": "string" }, "customer_email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "title": "Customer Email" }, "customer_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Customer Name" }, "description": { "maxLength": 50000, "minLength": 1, "title": "Description", "type": "string" }, "priority": { "default": "medium", "enum": [ "low", "medium", "high", "urgent" ], "title": "Priority", "type": "string" }, "subject": { "maxLength": 500, "minLength": 1, "title": "Subject", "type": "string" } }, "required": [ "subject", "description" ], "title": "CreateTicketRequest", "type": "object" }, "CreditBalanceResponse": { "properties": { "credits_remaining": { "description": "Operation credits left this period (-1 = unlimited)", "title": "Credits Remaining", "type": "integer" }, "credits_total": { "description": "Credits allocated this period (-1 = unlimited)", "title": "Credits Total", "type": "integer" }, "credits_used": { "description": "Credits consumed this period", "title": "Credits Used", "type": "integer" }, "overage_credits_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Credits consumed beyond plan allocation", "title": "Overage Credits Used" }, "overage_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "block | allow", "title": "Overage Policy" }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current subscription tier/plan", "title": "Plan" }, "unlimited": { "description": "True for enterprise/unmetered plans", "title": "Unlimited", "type": "boolean" } }, "required": [ "credits_remaining", "credits_total", "credits_used", "unlimited" ], "title": "CreditBalanceResponse", "type": "object" }, "CreditTopupRequest": { "properties": { "amount_usd": { "description": "Top-up amount in USD (must be 10, 25, or 50)", "title": "Amount Usd", "type": "number" } }, "required": [ "amount_usd" ], "title": "CreditTopupRequest", "type": "object" }, "CursorPage_AnomalyResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/AnomalyResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[AnomalyResponse]", "type": "object" }, "CursorPage_CollectionResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/CollectionResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[CollectionResponse]", "type": "object" }, "CursorPage_JobResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/JobResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[JobResponse]", "type": "object" }, "CursorPage_PolicyVersion_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/PolicyVersion" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[PolicyVersion]", "type": "object" }, "CursorPage_TieredMemoryResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/TieredMemoryResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[TieredMemoryResponse]", "type": "object" }, "CursorPage_TransitionResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/TransitionResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[TransitionResponse]", "type": "object" }, "CursorPage_WebhookResponse_": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/WebhookResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items" ], "title": "CursorPage[WebhookResponse]", "type": "object" }, "DailyUsage": { "description": "Daily usage statistics.", "properties": { "avg_latency_ms": { "title": "Avg Latency Ms", "type": "number" }, "date": { "title": "Date", "type": "string" }, "failed_requests": { "title": "Failed Requests", "type": "integer" }, "successful_requests": { "title": "Successful Requests", "type": "integer" }, "total_requests": { "title": "Total Requests", "type": "integer" } }, "required": [ "date", "total_requests", "successful_requests", "failed_requests", "avg_latency_ms" ], "title": "DailyUsage", "type": "object" }, "DataExportRequest": { "description": "Request for data export.\n\nScope the export one of two ways:\n\n- ``include``: an explicit allow-list of sections. When provided, ONLY those\n sections are returned \u2014 the filter is honored strictly (2026-06-03 eval:\n a request for ``[\"collections\"]`` must NOT return memories / profile /\n API-key metadata). Allowed values: ``collections``, ``memories``,\n ``trajectories``, ``api_keys``, ``profile``.\n- Legacy boolean flags below, used only when ``include`` is omitted.\n\nAPI-key metadata is NEVER exported unless explicitly requested (via\n``include`` containing ``api_keys`` or ``include_api_keys=true``) \u2014 it is a\nprivacy-sensitive section and was previously returned unconditionally.", "properties": { "format": { "default": "json", "title": "Format", "type": "string" }, "include": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Include" }, "include_api_keys": { "default": false, "title": "Include Api Keys", "type": "boolean" }, "include_collections": { "default": true, "title": "Include Collections", "type": "boolean" }, "include_memories": { "default": true, "title": "Include Memories", "type": "boolean" }, "include_profile": { "default": true, "title": "Include Profile", "type": "boolean" }, "include_trajectories": { "default": false, "title": "Include Trajectories", "type": "boolean" } }, "title": "DataExportRequest", "type": "object" }, "DecisionCreate": { "additionalProperties": false, "description": "Request body for logging a decision and its outcome.", "properties": { "agent_confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Agent's self-reported confidence at decision time (0\u20131). Accepts `confidence` too.", "title": "Agent Confidence" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent ID that made the decision (if any)", "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection to scope this decision to (multi-tenant isolation)", "title": "Collection Id" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Surrounding context / reasoning at the time of the decision. Accepts `reasoning` as an alias.", "title": "Context" }, "correction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the linked correction (if was_corrected=True)", "title": "Correction Id" }, "decision_type": { "default": "general", "description": "Category of decision: tool_selection, code_change, deployment, etc. Defaults to 'general'.", "maxLength": 50, "minLength": 1, "title": "Decision Type", "type": "string" }, "description": { "description": "What the agent decided to do. Accepts `decision` as an alias.", "minLength": 1, "title": "Description", "type": "string" }, "extra_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Arbitrary structured data about the decision. Accepts `metadata` too.", "title": "Extra Metadata" }, "memory_count_at_decision": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Number of memories available when decision was made", "title": "Memory Count At Decision" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact memory used for this decision. Accepts selected_memory_id too. Providing this link lets retrieval apply the outcome to the intended memory instead of inferring a match from shared words.", "title": "Memory Id" }, "memory_ids": { "description": "Exact memories used for this decision. Accepts selected_memory_ids and source_memory_ids too.", "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "outcome": { "default": "unknown", "description": "Outcome of the decision: success, failure, partial, or unknown", "enum": [ "success", "failure", "partial", "unknown" ], "title": "Outcome", "type": "string" }, "reward": { "anyOf": [ { "maximum": 1.0, "minimum": -1.0, "type": "number" }, { "type": "null" } ], "description": "Optional numeric reward/feedback in [-1, 1]. Accepts `feedback` too.", "title": "Reward" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user ID to scope this decision to (multi-tenant isolation)", "title": "User Id" }, "user_satisfied": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the user was satisfied with the outcome", "title": "User Satisfied" }, "was_corrected": { "default": false, "description": "Whether the decision was subsequently corrected", "title": "Was Corrected", "type": "boolean" } }, "required": [ "description" ], "title": "DecisionCreate", "type": "object" }, "DecisionEvidenceManifest": { "additionalProperties": false, "description": "Exact evidence and runtime versions causally bound to a decision.", "properties": { "model": { "anyOf": [ { "$ref": "#/components/schemas/VersionedArtifact" }, { "type": "null" } ] }, "outcome_policy": { "anyOf": [ { "$ref": "#/components/schemas/OutcomeSourcePolicy" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "$ref": "#/components/schemas/VersionedArtifact" }, { "type": "null" } ] }, "references": { "items": { "$ref": "#/components/schemas/EvidenceReference" }, "maxItems": 200, "title": "References", "type": "array" }, "schema_version": { "const": "proofloop-evidence-v1", "default": "proofloop-evidence-v1", "title": "Schema Version", "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/VersionedArtifact" }, "maxItems": 50, "title": "Tools", "type": "array" } }, "title": "DecisionEvidenceManifest", "type": "object" }, "DecisionReceiptRequest": { "additionalProperties": false, "properties": { "action_probability": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 1.0, "type": "number" }, { "type": "null" } ], "description": "Behavior-policy propensity when the caller chose the action. Required for a caller-supplied choice with multiple candidates. In explore mode, supplying chosen_action_key records that exact external choice; omitting it asks Hebbrix to sample from its bounded epsilon-greedy policy.", "title": "Action Probability" }, "baseline_action_key": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Baseline Action Key" }, "candidates": { "items": { "$ref": "#/components/schemas/CandidateAction" }, "maxItems": 50, "minItems": 1, "title": "Candidates", "type": "array" }, "chosen_action_key": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Chosen Action Key" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "context": { "additionalProperties": true, "title": "Context", "type": "object" }, "decision_type": { "default": "action_selection", "maxLength": 100, "title": "Decision Type", "type": "string" }, "evidence_manifest": { "anyOf": [ { "$ref": "#/components/schemas/DecisionEvidenceManifest" }, { "type": "null" } ], "description": "Versioned memories, procedures, runtime artifacts, and permitted outcome sources bound to this pre-outcome receipt" }, "exploration_rate": { "default": 0.0, "description": "Epsilon for mode=explore. Bounded to [0, 0.2] and rejected for every other mode.", "maximum": 0.2, "minimum": 0.0, "title": "Exploration Rate", "type": "number" }, "idempotency_key": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Idempotency Key" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "mode": { "default": "recommend", "description": "observe logs a caller choice; recommend serves the conservative policy; explore either samples server-side or logs an explicit caller choice; shadow records a non-serving comparison choice.", "enum": [ "observe", "recommend", "explore", "shadow" ], "title": "Mode", "type": "string" }, "observation_window_seconds": { "anyOf": [ { "maximum": 31536000.0, "minimum": 60.0, "type": "integer" }, { "type": "null" } ], "title": "Observation Window Seconds" }, "policy_key": { "maxLength": 100, "minLength": 1, "title": "Policy Key", "type": "string" }, "proof_context_token": { "anyOf": [ { "maxLength": 131072, "minLength": 16, "type": "string" }, { "type": "null" } ], "description": "Automatic tenant-bound evidence token returned by Hebbrix search/chat. Use this instead of manually reconstructing evidence_manifest.", "title": "Proof Context Token" }, "trace_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "External end-user scope within the account", "title": "User Id" } }, "required": [ "policy_key", "candidates" ], "title": "DecisionReceiptRequest", "type": "object" }, "DecisionResponse": { "description": "Response schema for a single decision record.", "properties": { "account_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account User Id" }, "agent_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Agent Confidence" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context" }, "correction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correction Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "decision_type": { "title": "Decision Type", "type": "string" }, "description": { "title": "Description", "type": "string" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" }, "extra_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extra Metadata" }, "id": { "title": "Id", "type": "string" }, "memory_count_at_decision": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Memory Count At Decision" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" }, "memory_ids": { "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "outcome": { "title": "Outcome", "type": "string" }, "similarity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Similarity" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "user_satisfied": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "User Satisfied" }, "was_corrected": { "title": "Was Corrected", "type": "boolean" } }, "required": [ "id", "agent_id", "decision_type", "description", "context", "outcome", "user_satisfied", "was_corrected", "correction_id", "agent_confidence", "memory_count_at_decision", "extra_metadata", "created_at" ], "title": "DecisionResponse", "type": "object" }, "DeleteMemoryRequest": { "description": "Request model for deleting memory.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "memory_id": { "title": "Memory Id", "type": "string" } }, "required": [ "memory_id", "collection_id" ], "title": "DeleteMemoryRequest", "type": "object" }, "DeliveryStatistics": { "description": "Aggregated webhook delivery statistics (PDF contract).", "properties": { "failed": { "title": "Failed", "type": "integer" }, "last_delivery_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Delivery At" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "last_failure_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Failure At" }, "last_success_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Success At" }, "success_rate": { "title": "Success Rate", "type": "number" }, "successful": { "title": "Successful", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "total", "successful", "failed", "success_rate" ], "title": "DeliveryStatistics", "type": "object" }, "DialecticChatRequest": { "additionalProperties": false, "description": "Dialectic reasoning request (natural language queries about users).\n\nEnables natural language queries like:\n- \"What motivates this user?\"\n- \"What are their professional interests?\"\n- \"What communication style do they prefer?\"", "properties": { "app_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope reasoning to a single collection (multi-tenant isolation)", "title": "Collection Id" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope reasoning to a single end-user (multi-tenant isolation)", "title": "End User Id" }, "include_memories": { "default": true, "description": "Include relevant memories in reasoning context", "title": "Include Memories", "type": "boolean" }, "memory_limit": { "default": 10, "description": "Max memories to include for context", "maximum": 50.0, "minimum": 1.0, "title": "Memory Limit", "type": "integer" }, "message": { "anyOf": [ { "maxLength": 2000, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Alias for 'question' \u2014 accepts 'user_message' (PDF) too", "title": "Message" }, "namespace": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "observer_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Optional agent ID for scoped profile access", "title": "Observer Id" }, "question": { "anyOf": [ { "maxLength": 2000, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Natural language question about the user", "title": "Question" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional caller-provided session id", "title": "Session Id" } }, "title": "DialecticChatRequest", "type": "object" }, "DialecticChatResponse": { "description": "Response from dialectic reasoning endpoint.\n\nExposes the assistant's reply under two keys for contract compatibility:\n- ``response`` (legacy)\n- ``assistant_message`` (PDF contract)\n\nAlso includes a ``session_id`` (generated per-request if not tracked\nserver-side) so that clients implementing multi-turn UX have a stable\nidentifier to pass back.", "properties": { "assistant_message": { "title": "Assistant Message", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "question": { "title": "Question", "type": "string" }, "reasoning": { "additionalProperties": true, "title": "Reasoning", "type": "object" }, "response": { "title": "Response", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "sources": { "additionalProperties": true, "title": "Sources", "type": "object" } }, "required": [ "response", "assistant_message", "session_id", "question", "reasoning", "sources", "metadata" ], "title": "DialecticChatResponse", "type": "object" }, "DocumentStatus": { "description": "Document processing status - TWO-PHASE ARCHITECTURE.\n\nLifecycle:\n1. UPLOADED \u2192 Initial state after file upload\n2. PROCESSING \u2192 Phase 1 in progress (extract, chunk, embed, store in Qdrant)\n3. SEARCHABLE \u2192 Phase 1 complete - document is searchable in Qdrant (6-9 seconds)\n4. ENRICHING \u2192 Phase 2 in progress (profile extraction in background Celery queue)\n5. ENRICHED \u2192 Phase 2 complete - document has profile facts extracted\n6. PROCESSED \u2192 Legacy: kept for backward compatibility (same as ENRICHED)\n7. FAILED \u2192 Processing failed at any phase\n\nKey insight: Users can search immediately after SEARCHABLE status (6-9s).\nProfile enrichment (ENRICHING \u2192 ENRICHED) runs in background without blocking.", "enum": [ "uploaded", "processing", "searchable", "enriching", "enriched", "processed", "failed", "deleted" ], "title": "DocumentStatus", "type": "string" }, "DocumentType": { "description": "Document type categories.", "enum": [ "pdf", "word", "powerpoint", "excel", "csv", "markdown", "html", "text", "image", "rtf", "other" ], "title": "DocumentType", "type": "string" }, "DocumentUpdate": { "additionalProperties": false, "description": "Schema for document update request.", "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" } }, "title": "DocumentUpdate", "type": "object" }, "EndpointBreakdown": { "description": "Breakdown of usage by endpoint type.", "properties": { "count": { "description": "Number of requests this month", "title": "Count", "type": "integer" } }, "required": [ "count" ], "title": "EndpointBreakdown", "type": "object" }, "EndpointUsage": { "description": "Usage statistics for a specific endpoint.", "properties": { "avg_latency_ms": { "title": "Avg Latency Ms", "type": "number" }, "endpoint": { "title": "Endpoint", "type": "string" }, "failure_count": { "title": "Failure Count", "type": "integer" }, "method": { "title": "Method", "type": "string" }, "request_count": { "title": "Request Count", "type": "integer" }, "success_count": { "title": "Success Count", "type": "integer" } }, "required": [ "endpoint", "method", "request_count", "success_count", "failure_count", "avg_latency_ms" ], "title": "EndpointUsage", "type": "object" }, "EnterpriseContactRequest": { "description": "Enterprise sales inquiry form data.", "properties": { "company": { "maxLength": 200, "minLength": 1, "title": "Company", "type": "string" }, "company_size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company size range", "title": "Company Size" }, "current_solution": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Current memory/context solution if any", "title": "Current Solution" }, "email": { "description": "Work email address", "format": "email", "title": "Email", "type": "string" }, "estimated_monthly_operations": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated monthly API operations", "title": "Estimated Monthly Operations" }, "first_name": { "maxLength": 100, "minLength": 1, "title": "First Name", "type": "string" }, "job_title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Job Title" }, "last_name": { "maxLength": 100, "minLength": 1, "title": "Last Name", "type": "string" }, "use_case": { "description": "How they plan to use Hebbrix", "maxLength": 2000, "minLength": 10, "title": "Use Case", "type": "string" } }, "required": [ "first_name", "last_name", "email", "company", "use_case" ], "title": "EnterpriseContactRequest", "type": "object" }, "EnterpriseContactResponse": { "description": "Response after successful form submission.", "properties": { "message": { "default": "Thank you! Our team will reach out within 1 business day.", "title": "Message", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "title": "EnterpriseContactResponse", "type": "object" }, "EvaluateRequest": { "description": "Request model for agent evaluation.", "properties": { "agent_type": { "description": "memory_manager or answer_agent", "enum": [ "memory_manager", "answer_agent" ], "title": "Agent Type", "type": "string" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "num_episodes": { "default": 10, "maximum": 100.0, "minimum": 1.0, "title": "Num Episodes", "type": "integer" } }, "required": [ "agent_type" ], "title": "EvaluateRequest", "type": "object" }, "EvidenceReference": { "additionalProperties": false, "properties": { "digest": { "anyOf": [ { "pattern": "^(?:sha256:)?[0-9a-fA-F]{64}$", "type": "string" }, { "type": "null" } ], "description": "Optional SHA-256 digest of the exact evidence revision", "title": "Digest" }, "kind": { "enum": [ "memory", "correction", "procedure", "document", "external" ], "title": "Kind", "type": "string" }, "reference_id": { "maxLength": 255, "minLength": 1, "title": "Reference Id", "type": "string" }, "revision": { "anyOf": [ { "maxLength": 160, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Revision" }, "role": { "default": "supporting", "enum": [ "supporting", "counterevidence", "constraint", "instruction" ], "title": "Role", "type": "string" } }, "required": [ "kind", "reference_id" ], "title": "EvidenceReference", "type": "object" }, "ExecuteProcedureRequest": { "description": "Request model for executing a procedure.", "properties": { "input_state": { "additionalProperties": true, "title": "Input State", "type": "object" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" } }, "required": [ "input_state" ], "title": "ExecuteProcedureRequest", "type": "object" }, "FastBatchIngestRequest": { "description": "All-or-retry batch accepted by the canonical ingestion service.", "example": { "collection_id": "col_abc123", "memories": [ { "content": "User prefers dark mode.", "importance": 0.6 }, { "content": "User works at a tech company.", "importance": 0.7 } ] }, "properties": { "app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "enable_bm25": { "default": true, "title": "Enable Bm25", "type": "boolean" }, "enable_knowledge_graph": { "default": true, "title": "Enable Knowledge Graph", "type": "boolean" }, "enable_profile_extraction": { "default": true, "title": "Enable Profile Extraction", "type": "boolean" }, "enable_tier_management": { "default": true, "title": "Enable Tier Management", "type": "boolean" }, "memories": { "items": { "$ref": "#/components/schemas/FastMemoryInput" }, "maxItems": 2000, "minItems": 1, "title": "Memories", "type": "array" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "wait_for_index": { "default": false, "description": "Block until dense and sparse search indexes acknowledge every memory. The default accepts the atomic PostgreSQL/outbox commit and indexes asynchronously.", "title": "Wait For Index", "type": "boolean" } }, "required": [ "memories" ], "title": "FastBatchIngestRequest", "type": "object" }, "FastBatchIngestResponse": { "description": "Truthful durable/search delivery result for one ingestion batch.", "example": { "breakdown": { "postgresql_outbox_commit": 0.1 }, "collection_id": "col_abc123", "failed": 0, "features_completed": { "bm25": true, "embeddings": true, "postgresql": true, "qdrant": true }, "memories_per_second": 2.5, "processed": 2, "success": true, "time_seconds": 0.8 }, "properties": { "breakdown": { "additionalProperties": { "type": "number" }, "title": "Breakdown", "type": "object" }, "collection_id": { "title": "Collection Id", "type": "string" }, "failed": { "title": "Failed", "type": "integer" }, "features_completed": { "additionalProperties": { "type": "boolean" }, "title": "Features Completed", "type": "object" }, "memories_per_second": { "title": "Memories Per Second", "type": "number" }, "memory_ids": { "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "processed": { "title": "Processed", "type": "integer" }, "processing_status": { "default": "processing", "title": "Processing Status", "type": "string" }, "searchable": { "default": false, "title": "Searchable", "type": "boolean" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Url" }, "success": { "title": "Success", "type": "boolean" }, "time_seconds": { "title": "Time Seconds", "type": "number" } }, "required": [ "success", "processed", "failed", "collection_id", "time_seconds", "memories_per_second", "breakdown", "features_completed" ], "title": "FastBatchIngestResponse", "type": "object" }, "FastMemoryInput": { "description": "One immutable memory accepted by the canonical ingestion service.", "example": { "content": "The user prefers Python over JavaScript.", "importance": 0.7, "metadata": { "source": "conversation" }, "tags": [ "preference", "programming" ] }, "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "chunk_index": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Chunk Index" }, "content": { "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "importance": { "default": 0.5, "maximum": 1.0, "minimum": 0.0, "title": "Importance", "type": "number" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "source_reference": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Source Reference" }, "source_type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "total_chunks": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Total Chunks" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "content" ], "title": "FastMemoryInput", "type": "object" }, "FastSingleMemoryRequest": { "example": { "content": "The user prefers Python over JavaScript.", "importance": 0.7, "metadata": { "source": "conversation" }, "tags": [ "preference", "programming" ] }, "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "app_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "App Id" }, "async_upgrade": { "default": false, "description": "Queue ML fact extraction after the durable verbatim write.", "title": "Async Upgrade", "type": "boolean" }, "chunk_index": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Chunk Index" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "content": { "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "importance": { "default": 0.5, "maximum": 1.0, "minimum": 0.0, "title": "Importance", "type": "number" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "namespace": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "source_reference": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Source Reference" }, "source_type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "total_chunks": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Total Chunks" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" }, "wait_for_index": { "default": false, "description": "Block until dense and sparse indexes acknowledge the memory. Default false returns after the atomic PostgreSQL/outbox commit.", "title": "Wait For Index", "type": "boolean" } }, "required": [ "content" ], "title": "FastSingleMemoryRequest", "type": "object" }, "FastSingleMemoryResponse": { "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "memory_id": { "title": "Memory Id", "type": "string" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "processing_status": { "title": "Processing Status", "type": "string" }, "searchable": { "title": "Searchable", "type": "boolean" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Url" }, "success": { "title": "Success", "type": "boolean" }, "time_ms": { "title": "Time Ms", "type": "number" } }, "required": [ "success", "memory_id", "collection_id", "processing_status", "time_ms", "searchable" ], "title": "FastSingleMemoryResponse", "type": "object" }, "FeedbackRequest": { "description": "Request model for procedure feedback.", "properties": { "execution_id": { "title": "Execution Id", "type": "string" }, "reward": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reward" }, "success": { "title": "Success", "type": "boolean" }, "user_feedback": { "anyOf": [ { "maximum": 1.0, "minimum": -1.0, "type": "number" }, { "type": "null" } ], "title": "User Feedback" } }, "required": [ "execution_id", "success" ], "title": "FeedbackRequest", "type": "object" }, "FeedbackResponse": { "description": "Response after submitting feedback.", "properties": { "applied_adjustment": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Applied Adjustment" }, "feedback_id": { "title": "Feedback Id", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "feedback_id", "message" ], "title": "FeedbackResponse", "type": "object" }, "FeedbackStats": { "description": "Statistics about user feedback.", "properties": { "avg_feedback_per_query": { "title": "Avg Feedback Per Query", "type": "number" }, "missing_results_count": { "title": "Missing Results Count", "type": "integer" }, "positive_feedback_rate": { "title": "Positive Feedback Rate", "type": "number" }, "ranking_feedback_count": { "title": "Ranking Feedback Count", "type": "integer" }, "recent_feedback": { "items": { "additionalProperties": true, "type": "object" }, "title": "Recent Feedback", "type": "array" }, "relevance_feedback_count": { "title": "Relevance Feedback Count", "type": "integer" }, "total_feedback": { "title": "Total Feedback", "type": "integer" } }, "required": [ "total_feedback", "relevance_feedback_count", "ranking_feedback_count", "missing_results_count", "positive_feedback_rate", "avg_feedback_per_query", "recent_feedback" ], "title": "FeedbackStats", "type": "object" }, "ForgotPasswordRequest": { "description": "Forgot password request schema - sends OTP to email.", "properties": { "email": { "format": "email", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "ForgotPasswordRequest", "type": "object" }, "ForgotPasswordResponse": { "description": "Forgot password response schema.", "properties": { "email_sent": { "default": true, "title": "Email Sent", "type": "boolean" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "ForgotPasswordResponse", "type": "object" }, "GetFixSuggestionsRequest": { "description": "Request for fix suggestions.", "properties": { "code_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Code around the error", "title": "Code Context" }, "error_message": { "description": "The error message", "title": "Error Message", "type": "string" }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Type of error", "title": "Error Type" }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File where error occurred", "title": "File Path" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Programming language", "title": "Language" } }, "required": [ "error_message" ], "title": "GetFixSuggestionsRequest", "type": "object" }, "GoogleAuthRequest": { "description": "Google OAuth code exchange request.", "properties": { "code": { "title": "Code", "type": "string" }, "redirect_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Uri" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, "required": [ "code" ], "title": "GoogleAuthRequest", "type": "object" }, "GoogleAuthResponse": { "description": "Google OAuth response schema.", "properties": { "access_token": { "title": "Access Token", "type": "string" }, "email": { "title": "Email", "type": "string" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "is_new_user": { "default": false, "title": "Is New User", "type": "boolean" }, "token_type": { "default": "bearer", "title": "Token Type", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "access_token", "user_id", "email" ], "title": "GoogleAuthResponse", "type": "object" }, "GraphSearchRequest": { "description": "JSON body for graph search. Accepts `query` OR `entity` (PDF contract).", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "depth": { "default": 2, "maximum": 5.0, "minimum": 1.0, "title": "Depth", "type": "integer" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" } }, "title": "GraphSearchRequest", "type": "object" }, "GraphStatsResponse": { "description": "Knowledge graph statistics.", "properties": { "entity_count": { "title": "Entity Count", "type": "integer" }, "memory_count": { "title": "Memory Count", "type": "integer" }, "most_connected_entities": { "items": { "additionalProperties": true, "type": "object" }, "title": "Most Connected Entities", "type": "array" }, "relationship_count": { "title": "Relationship Count", "type": "integer" }, "relationship_type_distribution": { "additionalProperties": { "type": "integer" }, "title": "Relationship Type Distribution", "type": "object" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "memory_count", "entity_count", "relationship_count", "most_connected_entities", "relationship_type_distribution" ], "title": "GraphStatsResponse", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "ImportStatus": { "description": "Import status.", "enum": [ "pending", "processing", "completed", "failed" ], "title": "ImportStatus", "type": "string" }, "InferenceRequest": { "description": "Request schema for inference operations.", "properties": { "apply_rules": { "default": true, "title": "Apply Rules", "type": "boolean" }, "max_path_length": { "default": 3, "maximum": 4.0, "minimum": 2.0, "title": "Max Path Length", "type": "integer" }, "relation_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relation Types" } }, "title": "InferenceRequest", "type": "object" }, "InsertMemoryRequest": { "description": "Request model for inserting new memory.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "content": { "title": "Content", "type": "string" }, "importance": { "default": 0.5, "maximum": 1.0, "minimum": 0.0, "title": "Importance", "type": "number" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "required": [ "content", "collection_id" ], "title": "InsertMemoryRequest", "type": "object" }, "IntegrationCallbackRequest": { "properties": { "code": { "title": "Code", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "code", "state" ], "title": "IntegrationCallbackRequest", "type": "object" }, "IntegrationConnectResponse": { "properties": { "auth_url": { "title": "Auth Url", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "auth_url", "state" ], "title": "IntegrationConnectResponse", "type": "object" }, "IntegrationResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "id": { "title": "Id", "type": "string" }, "last_sync_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sync At" }, "memory_count": { "default": 0, "title": "Memory Count", "type": "integer" }, "provider": { "title": "Provider", "type": "string" }, "status": { "title": "Status", "type": "string" }, "sync_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sync Metadata" } }, "required": [ "id", "provider", "status" ], "title": "IntegrationResponse", "type": "object" }, "IntegrationStatusResponse": { "properties": { "connected": { "title": "Connected", "type": "boolean" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "last_sync_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sync At" }, "memory_count": { "default": 0, "title": "Memory Count", "type": "integer" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, "required": [ "connected" ], "title": "IntegrationStatusResponse", "type": "object" }, "InvalidateFactRequest": { "description": "Request model for invalidating facts.", "properties": { "object": { "maxLength": 512, "minLength": 1, "title": "Object", "type": "string" }, "predicate": { "maxLength": 128, "minLength": 1, "title": "Predicate", "type": "string" }, "subject": { "maxLength": 512, "minLength": 1, "title": "Subject", "type": "string" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the fact stopped being true. Defaults to the observation time when omitted, allowing retroactive bitemporal correction.", "title": "Valid Until" } }, "required": [ "subject", "predicate", "object" ], "title": "InvalidateFactRequest", "type": "object" }, "InvoiceResponse": { "description": "Invoice details.", "properties": { "amount_due": { "title": "Amount Due", "type": "number" }, "amount_paid": { "title": "Amount Paid", "type": "number" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Created At" }, "currency": { "title": "Currency", "type": "string" }, "hosted_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hosted Invoice Url" }, "id": { "title": "Id", "type": "string" }, "invoice_pdf_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Pdf Url" }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Paid At" }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Period End" }, "period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Period Start" }, "status": { "title": "Status", "type": "string" }, "total": { "title": "Total", "type": "number" } }, "required": [ "id", "status", "currency", "total", "amount_paid", "amount_due", "period_start", "period_end", "paid_at", "hosted_invoice_url", "invoice_pdf_url", "created_at" ], "title": "InvoiceResponse", "type": "object" }, "JobResponse": { "description": "Job response schema.", "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "current_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Step" }, "duration_seconds": { "title": "Duration Seconds", "type": "number" }, "error_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error Details" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "id": { "title": "Id", "type": "string" }, "job_metadata": { "additionalProperties": true, "title": "Job Metadata", "type": "object" }, "parameters": { "additionalProperties": true, "title": "Parameters", "type": "object" }, "progress": { "title": "Progress", "type": "number" }, "queued_at": { "format": "date-time", "title": "Queued At", "type": "string" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "total_steps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Steps" }, "type": { "$ref": "#/components/schemas/JobType" } }, "required": [ "id", "type", "status", "progress", "parameters", "queued_at", "duration_seconds", "job_metadata" ], "title": "JobResponse", "type": "object" }, "JobStatus": { "description": "Job execution status.", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "title": "JobStatus", "type": "string" }, "JobType": { "description": "Job type.", "enum": [ "rl_training", "bulk_import", "data_export", "backup", "consolidation", "kg_rebuild", "chat_post_response", "cleanup" ], "title": "JobType", "type": "string" }, "KeyResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "is_active": { "title": "Is Active", "type": "boolean" }, "key_preview": { "title": "Key Preview", "type": "string" }, "last_validated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Validated At" }, "provider": { "title": "Provider", "type": "string" }, "validation_status": { "title": "Validation Status", "type": "string" } }, "required": [ "provider", "key_preview", "is_active", "validation_status" ], "title": "KeyResponse", "type": "object" }, "LearnProcedureRequest": { "description": "Request model for learning from examples.", "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "examples": { "items": { "additionalProperties": true, "type": "object" }, "title": "Examples", "type": "array" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "examples" ], "title": "LearnProcedureRequest", "type": "object" }, "LogoutResponse": { "description": "Logout response schema.", "properties": { "message": { "title": "Message", "type": "string" }, "revoked": { "default": true, "title": "Revoked", "type": "boolean" } }, "required": [ "message" ], "title": "LogoutResponse", "type": "object" }, "MFADisableOTPResponse": { "description": "Response for email OTP request.", "properties": { "email_masked": { "title": "Email Masked", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message", "email_masked" ], "title": "MFADisableOTPResponse", "type": "object" }, "MFADisableRequest": { "description": "MFA disable request - multiple verification options for different account types.", "properties": { "backup_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Backup Code" }, "email_otp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Otp" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "totp_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Code" } }, "title": "MFADisableRequest", "type": "object" }, "MFADisableResponse": { "description": "MFA disable response.", "properties": { "message": { "title": "Message", "type": "string" }, "mfa_enabled": { "default": false, "title": "Mfa Enabled", "type": "boolean" } }, "required": [ "message" ], "title": "MFADisableResponse", "type": "object" }, "MFALoginOTPResponse": { "description": "Response for login email OTP request.", "properties": { "email_masked": { "title": "Email Masked", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message", "email_masked" ], "title": "MFALoginOTPResponse", "type": "object" }, "MFARequiredResponse": { "description": "Response when MFA verification is required.", "properties": { "message": { "default": "Multi-factor authentication required", "title": "Message", "type": "string" }, "mfa_required": { "default": true, "title": "Mfa Required", "type": "boolean" }, "mfa_token": { "title": "Mfa Token", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "mfa_token", "user_id" ], "title": "MFARequiredResponse", "type": "object" }, "MFASetupCompleteResponse": { "description": "MFA setup completion response with backup codes.", "properties": { "backup_codes": { "items": { "type": "string" }, "title": "Backup Codes", "type": "array" }, "backup_codes_count": { "title": "Backup Codes Count", "type": "integer" }, "message": { "title": "Message", "type": "string" }, "warning": { "default": "Save these backup codes in a secure location. They will not be shown again.", "title": "Warning", "type": "string" } }, "required": [ "message", "backup_codes", "backup_codes_count" ], "title": "MFASetupCompleteResponse", "type": "object" }, "MFASetupInitResponse": { "description": "MFA setup initiation response.", "properties": { "message": { "default": "Scan the QR code with your authenticator app, then verify with a code.", "title": "Message", "type": "string" }, "qr_uri": { "title": "Qr Uri", "type": "string" }, "secret": { "title": "Secret", "type": "string" } }, "required": [ "secret", "qr_uri" ], "title": "MFASetupInitResponse", "type": "object" }, "MFASetupOTPResponse": { "description": "Response for MFA setup email OTP request.", "properties": { "email_masked": { "title": "Email Masked", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message", "email_masked" ], "title": "MFASetupOTPResponse", "type": "object" }, "MFASetupRequest": { "description": "Request body for MFA setup.", "properties": { "force_new": { "default": false, "title": "Force New", "type": "boolean" } }, "title": "MFASetupRequest", "type": "object" }, "MFASetupVerifyRequest": { "description": "MFA setup verification request.", "properties": { "code": { "title": "Code", "type": "string" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "totp", "title": "Method" } }, "required": [ "code" ], "title": "MFASetupVerifyRequest", "type": "object" }, "MFAStatusResponse": { "description": "MFA status response.", "properties": { "backup_codes_remaining": { "title": "Backup Codes Remaining", "type": "integer" }, "mfa_enabled": { "title": "Mfa Enabled", "type": "boolean" }, "setup_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Setup Date" } }, "required": [ "mfa_enabled", "backup_codes_remaining" ], "title": "MFAStatusResponse", "type": "object" }, "MFAVerifyRequest": { "description": "MFA verification request (login flow).", "properties": { "code": { "title": "Code", "type": "string" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "totp", "title": "Method" } }, "required": [ "code" ], "title": "MFAVerifyRequest", "type": "object" }, "MFAVerifyResponse": { "description": "MFA verification response for login flow - returns access token.", "properties": { "access_token": { "title": "Access Token", "type": "string" }, "email": { "title": "Email", "type": "string" }, "message": { "title": "Message", "type": "string" }, "token_type": { "default": "bearer", "title": "Token Type", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "access_token", "user_id", "email", "message" ], "title": "MFAVerifyResponse", "type": "object" }, "MatchProceduresRequest": { "additionalProperties": true, "description": "Natural-language context plus its explicit retrieval scope.\n\nOlder clients sent an arbitrary flat context object, while newer SDKs use a\nnested ``context`` object. Both remain valid; scope controls are removed\nbefore matching so they cannot accidentally influence procedure ranking.", "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context" }, "include_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Global" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "situation": { "anyOf": [ { "maxLength": 10000, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Situation" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "title": "MatchProceduresRequest", "type": "object" }, "MediaType": { "description": "Media file type.", "enum": [ "audio", "video" ], "title": "MediaType", "type": "string" }, "MediaUpdate": { "additionalProperties": false, "description": "Schema for media update request.", "properties": { "collection_id": { "anyOf": [ { "maxLength": 36, "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "tags": { "anyOf": [ { "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "title": "Tags" } }, "title": "MediaUpdate", "type": "object" }, "MemoryAdd": { "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Agent ID for per-agent scoping (multi-agent systems).", "title": "Agent Id" }, "app_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Application identifier for app-specific isolation (like Mem0's agent_id)", "title": "App Id" }, "async_dispatch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When true (and infer=true), returns 202 + job_id immediately and runs extraction in the background; poll /v1/memory-jobs/{job_id}. Use for latency-sensitive callers since extraction is LLM-bound. Omitted (null) uses the server default (MEMORIES_INFER_ASYNC_DEFAULT); an explicit true/false always wins.", "title": "Async Dispatch" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Explicit collection ID. Auto-resolves if not provided.", "title": "Collection Id" }, "content": { "anyOf": [ { "maxLength": 50000, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Raw memory content. Used when infer=false or as fallback.", "title": "Content" }, "importance": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Explicit importance (0-1) for the direct-store path (infer=false). When set, the stored memory uses this EXACT value instead of the server's auto-computed importance. Omitted (null) keeps auto-scoring. Ignored on the infer=true path (each extracted fact is scored individually).", "title": "Importance" }, "infer": { "default": true, "description": "When true (default), extract structured facts via the same LLM extract-and-resolve pipeline as /v1/memories/process (clean atomic facts + contradiction/supersession). When false, store content as-is verbatim (single memory), identical to /v1/memories/raw.", "title": "Infer", "type": "boolean" }, "messages": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MemoryAddMessage" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "Conversation turns for fact extraction. Each message has role + content.", "title": "Messages" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "namespace": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Namespace within the app for further isolation", "title": "Namespace" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Run ID for per-run scoping.", "title": "Run Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional external source identifier.", "title": "Source Reference" }, "source_type": { "default": "text", "description": "Source type used by the direct-store path.", "title": "Source Type", "type": "string" }, "tags": { "anyOf": [ { "items": { "maxLength": 128, "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "End-user ID (for multi-tenant apps tracking memories per end-user)", "title": "User Id" }, "wait_for_index": { "default": false, "description": "When true, block until the created memory is indexed and searchable (read-after-write consistency) before returning, instead of returning while indexing happens in the background.", "title": "Wait For Index", "type": "boolean" } }, "title": "MemoryAdd", "type": "object" }, "MemoryAddMessage": { "description": "A single message in a conversation turn (OpenAI/Mem0 format).", "properties": { "content": { "description": "Message text", "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "role": { "description": "Message role: user, assistant, system", "title": "Role", "type": "string" } }, "required": [ "role", "content" ], "title": "MemoryAddMessage", "type": "object" }, "MemoryAddResponse": { "description": "Response from the smart memory add endpoint.\n\n2026-06-03 eval: enriched with collection context + summary counts so\nclients don't have to tally the `results` array themselves. Each row's\n`id` is the PARENT Memory.id (retrievable via GET /v1/memories/{id});\nproposition-style ids (`uuid::subj=...`) are a search-layer artifact, not\nreturned here. Indexing is asynchronous \u2014 `processing_status=\"async\"` means\nthe memory is persisted and becoming searchable in the background.", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "created_count": { "default": 0, "title": "Created Count", "type": "integer" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "processing_status": { "default": "async", "title": "Processing Status", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/MemoryAddResultItem" }, "title": "Results", "type": "array" }, "searchable": { "default": false, "title": "Searchable", "type": "boolean" }, "skipped_count": { "default": 0, "title": "Skipped Count", "type": "integer" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Url" }, "updated_count": { "default": 0, "title": "Updated Count", "type": "integer" } }, "required": [ "results" ], "title": "MemoryAddResponse", "type": "object" }, "MemoryAddResultItem": { "description": "A single result from the memory add operation.", "properties": { "event": { "title": "Event", "type": "string" }, "id": { "title": "Id", "type": "string" }, "memory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "id", "event" ], "title": "MemoryAddResultItem", "type": "object" }, "MemoryContext": { "description": "Hebbrix context metadata.", "properties": { "collections_searched": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Collections Searched" }, "contradiction_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Contradiction Count" }, "degraded_stages": { "description": "Stages omitted or downgraded after exceeding a latency budget.", "items": { "type": "string" }, "title": "Degraded Stages", "type": "array" }, "feedback_reranking_applied": { "default": false, "title": "Feedback Reranking Applied", "type": "boolean" }, "generation_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Generation Ms" }, "grounding_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Grounding Score" }, "grounding_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grounding Status" }, "history_messages_used": { "default": 0, "title": "History Messages Used", "type": "integer" }, "learning_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "title": "Learning Ms" }, "memories": { "default": [], "items": { "$ref": "#/components/schemas/MemoryDetail" }, "title": "Memories", "type": "array" }, "memories_used": { "title": "Memories Used", "type": "integer" }, "memory_learning": { "anyOf": [ { "$ref": "#/components/schemas/MemoryLearningStatus" }, { "type": "null" } ] }, "outcome_reranking_applied": { "default": false, "title": "Outcome Reranking Applied", "type": "boolean" }, "processing_time_ms": { "title": "Processing Time Ms", "type": "integer" }, "profile_injected": { "title": "Profile Injected", "type": "boolean" }, "proof_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Automatic tenant-bound ProofLoop context for binding a later learning decision to the exact memories and runtime used.", "title": "Proof Context" }, "relevance_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Relevance Score" }, "retrieval_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retrieval Ms" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "stage_timings_ms": { "additionalProperties": { "type": "integer" }, "description": "Measured chat stage durations. Timed-out optional stages are marked separately in degraded_stages.", "title": "Stage Timings Ms", "type": "object" }, "strategy_used": { "title": "Strategy Used", "type": "string" } }, "required": [ "memories_used", "profile_injected", "processing_time_ms", "strategy_used" ], "title": "MemoryContext", "type": "object" }, "MemoryCreate": { "description": "Direct memory creation schema (raw storage, no inference).\n\nFor smart fact extraction from conversations, use POST /v1/memories instead.\n\n**Collection Resolution (Mem0-style):**\n- collection_id is now OPTIONAL\n- If not provided, auto-resolves based on app_id/namespace or uses default\n- If provided but deleted, auto-recovers the collection\n\n**Isolation Levels:**\n- No params: Uses user's `__default__` collection\n- app_id only: Uses `__app__{app_id}__default__` collection\n- app_id + namespace: Uses `__app__{app_id}__{namespace}__` collection\n- collection_id: Uses specific collection (with auto-recovery)", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "app_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Application identifier for app-specific isolation (like Mem0's agent_id)", "title": "App Id" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Explicit collection ID. If not provided, auto-resolves based on app_id/namespace or uses default.", "title": "Collection Id" }, "content": { "description": "Memory content (1-50000 chars)", "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "importance": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Importance score (0-1). If not provided, auto-calculated based on content analysis.", "title": "Importance" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "namespace": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Namespace within the app for further isolation", "title": "Namespace" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference" }, "source_type": { "default": "text", "title": "Source Type", "type": "string" }, "tags": { "anyOf": [ { "items": { "maxLength": 128, "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "wait_for_index": { "default": false, "description": "Observe indexing for up to 250ms. Returns 201 with searchable=true when ready; after a durable commit that still needs indexing, returns 202 with searchable=false, Retry-After, Location, status_url, and outbox_event_id while processing continues.", "title": "Wait For Index", "type": "boolean" } }, "required": [ "content" ], "title": "MemoryCreate", "type": "object" }, "MemoryCursorPage": { "description": "Memory page with an additive alias for memory-specific clients.\n\n``items`` remains the canonical cursor-pagination field. ``memories``\ncontains the same rows in the same order.", "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/MemoryResponse" }, "title": "Items", "type": "array" }, "memories": { "items": { "$ref": "#/components/schemas/MemoryResponse" }, "title": "Memories", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "previous_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Cursor" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count" } }, "required": [ "items", "memories" ], "title": "MemoryCursorPage", "type": "object" }, "MemoryDetail": { "description": "Individual memory used in the response.", "properties": { "content": { "title": "Content", "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "feedback_boost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Feedback Boost" }, "grounding": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Claim-level grounding receipt for this retrieved memory.", "title": "Grounding" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "low_confidence": { "default": false, "description": "True when soft grounding preserved a ranked but unverified candidate.", "title": "Low Confidence", "type": "boolean" }, "outcome_boost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Outcome Boost" }, "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rank" }, "relevance_calibration": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Request-scoped calibration receipt proving candidate-support evidence crossed the semantic verification boundary.", "title": "Relevance Calibration" }, "score": { "title": "Score", "type": "number" }, "source_memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical source-memory identity used by the evidence receipt.", "title": "Source Memory Id" } }, "required": [ "content", "score" ], "title": "MemoryDetail", "type": "object" }, "MemoryLearningStatus": { "description": "Issue 2: deterministic learning outcome contract. Chat learning runs\nASYNC after the response, so the in-request handler can't know final\nmemory_ids \u2014 it returns a job_id and status the client can rely on, instead\nof letting the LLM invent a \"saved\"/\"couldn't store\" outcome in its reply.", "properties": { "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Async learning job id (when status=queued).", "title": "Job Id" }, "memory_ids": { "description": "Stored memory ids (populated when known).", "items": { "type": "string" }, "title": "Memory Ids", "type": "array" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "status": { "default": "disabled", "description": "queued (async, in progress) | completed | rejected | disabled", "title": "Status", "type": "string" } }, "title": "MemoryLearningStatus", "type": "object" }, "MemoryProcessEvent": { "description": "A single event from memory processing.", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "event": { "title": "Event", "type": "string" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" }, "previous_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Content" }, "previous_memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Memory Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "event" ], "title": "MemoryProcessEvent", "type": "object" }, "MemoryProcessJobBatchStatusRequest": { "description": "Bounded status lookup for concurrent ingestion clients.", "properties": { "job_ids": { "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Job Ids", "type": "array" } }, "required": [ "job_ids" ], "title": "MemoryProcessJobBatchStatusRequest", "type": "object" }, "MemoryProcessJobBatchStatusResponse": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/MemoryProcessJobStatusResponse" }, "title": "Jobs", "type": "array" }, "missing_job_ids": { "items": { "type": "string" }, "title": "Missing Job Ids", "type": "array" } }, "required": [ "jobs", "missing_job_ids" ], "title": "MemoryProcessJobBatchStatusResponse", "type": "object" }, "MemoryProcessJobStatusResponse": { "description": "Status payload for async /v1/memories/process jobs.", "properties": { "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "job_id": { "title": "Job Id", "type": "string" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outbox Event Id" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "required": [ "job_id", "status" ], "title": "MemoryProcessJobStatusResponse", "type": "object" }, "MemoryProcessMessage": { "description": "A single message for the process endpoint.", "properties": { "content": { "description": "Message text", "maxLength": 50000, "minLength": 1, "title": "Content", "type": "string" }, "role": { "description": "Message role: user, assistant, system", "title": "Role", "type": "string" } }, "required": [ "role", "content" ], "title": "MemoryProcessMessage", "type": "object" }, "MemoryProcessRequest": { "properties": { "agent_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Agent ID for finer isolation.", "title": "Agent Id" }, "app_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Application identifier for isolation.", "title": "App Id" }, "async_dispatch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, server returns 202 + {job_id} immediately and the LLM-extraction work runs on a Celery worker. Client polls /v1/memories/jobs/{job_id} for the result. Omitted uses MEMORY_PROCESS_ASYNC_DEFAULT (true by default). Pass false only when the resulting events must be returned inline.", "title": "Async Dispatch" }, "collection_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Explicit collection ID.", "title": "Collection Id" }, "messages": { "description": "Conversation messages to process for memory extraction.", "items": { "$ref": "#/components/schemas/MemoryProcessMessage" }, "maxItems": 50, "minItems": 1, "title": "Messages", "type": "array" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "namespace": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Namespace within the app.", "title": "Namespace" }, "run_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Run ID for finer isolation.", "title": "Run Id" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "End-user ID for multi-tenant isolation.", "title": "User Id" } }, "required": [ "messages" ], "title": "MemoryProcessRequest", "type": "object" }, "MemoryProcessResponse": { "description": "Response from the memory process endpoint.", "properties": { "events": { "items": { "$ref": "#/components/schemas/MemoryProcessEvent" }, "title": "Events", "type": "array" }, "facts_extracted": { "title": "Facts Extracted", "type": "integer" }, "memories_created": { "title": "Memories Created", "type": "integer" }, "memories_unchanged": { "title": "Memories Unchanged", "type": "integer" }, "memories_updated": { "title": "Memories Updated", "type": "integer" } }, "required": [ "events", "facts_extracted", "memories_created", "memories_updated", "memories_unchanged" ], "title": "MemoryProcessResponse", "type": "object" }, "MemoryQuotaResponse": { "description": "Memory quota information for the current user.", "properties": { "is_unlimited": { "description": "Whether the tier has unlimited memories", "title": "Is Unlimited", "type": "boolean" }, "memories_limit": { "description": "Memory limit for current tier (-1 for unlimited)", "title": "Memories Limit", "type": "integer" }, "memories_used": { "description": "Total memories created (cumulative, lifetime)", "title": "Memories Used", "type": "integer" }, "percentage_used": { "description": "Percentage of quota used (0-100, null for unlimited)", "title": "Percentage Used", "type": "number" }, "remaining": { "description": "Remaining memories that can be created (-1 for unlimited)", "title": "Remaining", "type": "integer" }, "tier": { "description": "Current subscription tier (free, starter, pro, enterprise)", "title": "Tier", "type": "string" } }, "required": [ "tier", "memories_used", "memories_limit", "remaining", "percentage_used", "is_unlimited" ], "title": "MemoryQuotaResponse", "type": "object" }, "MemoryResponse": { "description": "Memory response schema.", "properties": { "access_count": { "title": "Access Count", "type": "integer" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "title": "Collection Id", "type": "string" }, "conflict_status": { "default": "none", "title": "Conflict Status", "type": "string" }, "content": { "title": "Content", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" }, "id": { "title": "Id", "type": "string" }, "importance": { "title": "Importance", "type": "number" }, "last_accessed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Accessed At" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Durable indexing event identity when indexing continues asynchronously.", "title": "Outbox Event Id" }, "processing_status": { "description": "Indexing/readiness state: 'pending' \u2192 'processing' \u2192 'completed' (searchable) or 'failed'. READ-AFTER-WRITE: a newly written memory is searchable once this reaches 'completed' (normally under one second when workers are healthy). Poll GET /v1/memories/{id} and wait for 'completed', or pass wait_for_index=true on the write to block until it is searchable.", "title": "Processing Status", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "searchable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True only when processing_status is completed. A 202 response with searchable=false means the PostgreSQL row and durable index event committed successfully and the client should poll status_url.", "title": "Searchable" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference" }, "source_type": { "title": "Source Type", "type": "string" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Relative readiness endpoint for this memory.", "title": "Status Url" }, "superseded_by_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Superseded By Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "id", "collection_id", "content", "importance", "source_type", "source_reference", "processing_status", "access_count", "last_accessed_at", "created_at", "updated_at" ], "title": "MemoryResponse", "type": "object" }, "MemoryUpdate": { "description": "Memory update schema.", "properties": { "content": { "anyOf": [ { "maxLength": 50000, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Content" }, "importance": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Importance" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "wait_for_index": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Wait For Index" } }, "title": "MemoryUpdate", "type": "object" }, "MemoryWithMetadata": { "description": "Memory response with metadata.", "properties": { "access_count": { "title": "Access Count", "type": "integer" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "title": "Collection Id", "type": "string" }, "conflict_status": { "default": "none", "title": "Conflict Status", "type": "string" }, "content": { "title": "Content", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" }, "id": { "title": "Id", "type": "string" }, "importance": { "title": "Importance", "type": "number" }, "last_accessed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Accessed At" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "outbox_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Durable indexing event identity when indexing continues asynchronously.", "title": "Outbox Event Id" }, "processing_status": { "description": "Indexing/readiness state: 'pending' \u2192 'processing' \u2192 'completed' (searchable) or 'failed'. READ-AFTER-WRITE: a newly written memory is searchable once this reaches 'completed' (normally under one second when workers are healthy). Poll GET /v1/memories/{id} and wait for 'completed', or pass wait_for_index=true on the write to block until it is searchable.", "title": "Processing Status", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "searchable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True only when processing_status is completed. A 202 response with searchable=false means the PostgreSQL row and durable index event committed successfully and the client should poll status_url.", "title": "Searchable" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference" }, "source_type": { "title": "Source Type", "type": "string" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Relative readiness endpoint for this memory.", "title": "Status Url" }, "superseded_by_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Superseded By Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "id", "collection_id", "content", "importance", "source_type", "source_reference", "processing_status", "access_count", "last_accessed_at", "created_at", "updated_at" ], "title": "MemoryWithMetadata", "type": "object" }, "MetricDefinitionRequest": { "additionalProperties": false, "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "guardrail_operator": { "anyOf": [ { "enum": [ "gte", "lte" ], "type": "string" }, { "type": "null" } ], "title": "Guardrail Operator" }, "guardrail_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Guardrail Threshold" }, "is_active": { "default": true, "title": "Is Active", "type": "boolean" }, "is_guardrail": { "default": false, "title": "Is Guardrail", "type": "boolean" }, "max_value": { "title": "Max Value", "type": "number" }, "metric_key": { "maxLength": 100, "minLength": 1, "title": "Metric Key", "type": "string" }, "min_value": { "title": "Min Value", "type": "number" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "objective": { "default": "maximize", "enum": [ "maximize", "minimize", "target" ], "title": "Objective", "type": "string" }, "observation_window_seconds": { "default": 604800, "maximum": 31536000.0, "minimum": 60.0, "title": "Observation Window Seconds", "type": "integer" }, "policy_key": { "maxLength": 100, "minLength": 1, "title": "Policy Key", "type": "string" }, "target_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Target Value" }, "tolerance": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Tolerance" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "External end-user scope within the account", "title": "User Id" }, "weight": { "default": 1.0, "exclusiveMinimum": 0.0, "maximum": 100.0, "title": "Weight", "type": "number" } }, "required": [ "policy_key", "metric_key", "name", "min_value", "max_value" ], "title": "MetricDefinitionRequest", "type": "object" }, "MissingResultRequest": { "description": "Request to report missing result.", "properties": { "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Additional context", "title": "Context" }, "expected_content": { "description": "Description of missing memory", "title": "Expected Content", "type": "string" }, "query": { "description": "Search query", "title": "Query", "type": "string" } }, "required": [ "query", "expected_content" ], "title": "MissingResultRequest", "type": "object" }, "ModelCost": { "description": "Cost information for a specific model.", "properties": { "description": { "description": "Human-readable description", "title": "Description", "type": "string" }, "model": { "description": "Model name", "title": "Model", "type": "string" }, "multiplier": { "description": "Token multiplier (1.0 = baseline gpt-5-mini)", "title": "Multiplier", "type": "number" } }, "required": [ "model", "multiplier", "description" ], "title": "ModelCost", "type": "object" }, "ModelPreferenceUpdate": { "description": "Update preferred model.", "properties": { "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, "title": "ModelPreferenceUpdate", "type": "object" }, "OutcomeBatchRequest": { "additionalProperties": false, "description": "Record typed outcomes, or use reward/success for the 30-second path.", "properties": { "idempotency_key": { "anyOf": [ { "maxLength": 150, "type": "string" }, { "type": "null" } ], "title": "Idempotency Key" }, "observations": { "items": { "$ref": "#/components/schemas/OutcomeInput" }, "maxItems": 20, "title": "Observations", "type": "array" }, "reward": { "anyOf": [ { "maximum": 1.0, "minimum": -1.0, "type": "number" }, { "type": "null" } ], "title": "Reward" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success" } }, "title": "OutcomeBatchRequest", "type": "object" }, "OutcomeInput": { "additionalProperties": false, "properties": { "confidence": { "default": 1.0, "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "evidence_digest": { "anyOf": [ { "pattern": "^(?:sha256:)?[0-9a-fA-F]{64}$", "type": "string" }, { "type": "null" } ], "description": "SHA-256 digest of the source event payload, never the payload itself", "title": "Evidence Digest" }, "idempotency_key": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Idempotency Key" }, "is_final": { "default": true, "title": "Is Final", "type": "boolean" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "metric_key": { "description": "reward and success are built-in. Every other metric_key must first be defined for the same policy and scope with POST /v1/learning/metrics.", "maxLength": 100, "minLength": 1, "title": "Metric Key", "type": "string" }, "observed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Observed At" }, "source": { "default": "explicit", "description": "Closed provenance enum: explicit, business_metric, verification, implicit, correction, or import.", "enum": [ "explicit", "business_metric", "verification", "implicit", "correction", "import" ], "title": "Source", "type": "string" }, "source_event_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Source Event Id" }, "source_system": { "anyOf": [ { "maxLength": 160, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Source System" }, "value": { "title": "Value", "type": "number" } }, "required": [ "metric_key", "value" ], "title": "OutcomeInput", "type": "object" }, "OutcomeSourcePolicy": { "additionalProperties": false, "properties": { "allowed_source_systems": { "items": { "type": "string" }, "maxItems": 50, "title": "Allowed Source Systems", "type": "array" }, "allowed_sources": { "items": { "enum": [ "explicit", "business_metric", "verification", "implicit", "correction", "import" ], "type": "string" }, "maxItems": 6, "minItems": 1, "title": "Allowed Sources", "type": "array" }, "require_source_event_id": { "default": false, "title": "Require Source Event Id", "type": "boolean" } }, "required": [ "allowed_sources" ], "title": "OutcomeSourcePolicy", "type": "object" }, "OverageSettingsResponse": { "description": "Current overage config.", "properties": { "overage_cap_usd": { "description": "Maximum overage spend per cycle (USD)", "title": "Overage Cap Usd", "type": "number" }, "overage_credits_used": { "description": "Overage credits consumed this cycle", "title": "Overage Credits Used", "type": "integer" }, "overage_enabled": { "description": "True if allow_overage policy is set", "title": "Overage Enabled", "type": "boolean" }, "overage_rate_usd_per_credit": { "description": "Price per overage credit (currently $0.002)", "title": "Overage Rate Usd Per Credit", "type": "number" } }, "required": [ "overage_enabled", "overage_cap_usd", "overage_credits_used", "overage_rate_usd_per_credit" ], "title": "OverageSettingsResponse", "type": "object" }, "OverageUpdateRequest": { "description": "Flip overage and/or adjust the cap.\n\nEither field is optional \u2014 send whichever you want to change.", "properties": { "overage_cap_usd": { "anyOf": [ { "maximum": 1000.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Max overage USD per cycle. Range: $0 \u2013 $1000.", "title": "Overage Cap Usd" }, "overage_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True to enable overage (continues after plan cap hit)", "title": "Overage Enabled" } }, "title": "OverageUpdateRequest", "type": "object" }, "PatchFactRequest": { "description": "Request to partially update a profile fact.", "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "fact_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fact Value" }, "importance": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Importance" } }, "title": "PatchFactRequest", "type": "object" }, "PathRequest": { "description": "Request schema for multi-hop path finding.", "properties": { "max_hops": { "default": 5, "maximum": 6.0, "minimum": 1.0, "title": "Max Hops", "type": "integer" }, "relation_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relation Types" }, "source_id": { "title": "Source Id", "type": "string" }, "target_id": { "title": "Target Id", "type": "string" } }, "required": [ "source_id", "target_id" ], "title": "PathRequest", "type": "object" }, "PaymentMethodResponse": { "description": "Payment method details.", "properties": { "card_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Card Brand" }, "card_exp_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Card Exp Month" }, "card_exp_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Card Exp Year" }, "card_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Card Last Four" }, "id": { "title": "Id", "type": "string" }, "is_default": { "title": "Is Default", "type": "boolean" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "type", "card_brand", "card_last_four", "card_exp_month", "card_exp_year", "is_default" ], "title": "PaymentMethodResponse", "type": "object" }, "PlanResponse": { "description": "Subscription plan details.", "properties": { "api_calls_per_month": { "title": "Api Calls Per Month", "type": "integer" }, "billing_interval": { "title": "Billing Interval", "type": "string" }, "credits_per_month": { "default": 0, "title": "Credits Per Month", "type": "integer" }, "currency": { "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "features": { "additionalProperties": true, "title": "Features", "type": "object" }, "id": { "title": "Id", "type": "string" }, "is_popular": { "default": false, "title": "Is Popular", "type": "boolean" }, "memory_limit": { "title": "Memory Limit", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "overage_rate_cents": { "default": 0, "title": "Overage Rate Cents", "type": "integer" }, "price_cents": { "title": "Price Cents", "type": "integer" }, "price_display": { "title": "Price Display", "type": "string" }, "tier": { "title": "Tier", "type": "string" }, "tokens_per_month": { "title": "Tokens Per Month", "type": "integer" }, "trial_days": { "title": "Trial Days", "type": "integer" } }, "required": [ "id", "name", "tier", "billing_interval", "price_cents", "price_display", "currency", "memory_limit", "api_calls_per_month", "tokens_per_month", "features", "description", "trial_days" ], "title": "PlanResponse", "type": "object" }, "PlanSwitchRequest": { "description": "Upgrade/downgrade request keyed by plan name or tier (e.g. 'starter', 'pro').\n\nAccepts either ``plan`` (legacy) or ``tier`` (PDF contract). Both populate\nthe same internal ``plan`` field so downstream code is unchanged.", "properties": { "billing_interval": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional 'monthly' or 'yearly'", "title": "Billing Interval" }, "plan": { "description": "Target plan tier or name (e.g. 'free', 'starter', 'pro', 'enterprise')", "title": "Plan", "type": "string" }, "prorate": { "default": true, "title": "Prorate", "type": "boolean" } }, "required": [ "plan" ], "title": "PlanSwitchRequest", "type": "object" }, "PolicyComparison": { "description": "Comparison between two policy versions.", "properties": { "baseline_version": { "title": "Baseline Version", "type": "string" }, "candidate_version": { "title": "Candidate Version", "type": "string" }, "is_improvement": { "title": "Is Improvement", "type": "boolean" }, "metrics_diff": { "additionalProperties": { "type": "number" }, "title": "Metrics Diff", "type": "object" }, "recommendation": { "title": "Recommendation", "type": "string" } }, "required": [ "baseline_version", "candidate_version", "metrics_diff", "is_improvement", "recommendation" ], "title": "PolicyComparison", "type": "object" }, "PolicyComparisonRequest": { "description": "Request to compare two policies.", "properties": { "agent_type": { "title": "Agent Type", "type": "string" }, "baseline_version": { "title": "Baseline Version", "type": "string" }, "candidate_version": { "title": "Candidate Version", "type": "string" } }, "required": [ "baseline_version", "candidate_version", "agent_type" ], "title": "PolicyComparisonRequest", "type": "object" }, "PolicyEvaluationRequest": { "additionalProperties": false, "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "limit": { "default": 500, "maximum": 2000.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "user_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "title": "PolicyEvaluationRequest", "type": "object" }, "PolicyPromotionRequest": { "description": "Request to promote policy to production.", "properties": { "agent_type": { "title": "Agent Type", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "version": { "title": "Version", "type": "string" } }, "required": [ "version", "agent_type" ], "title": "PolicyPromotionRequest", "type": "object" }, "PolicyRollbackRequest": { "description": "Request to rollback policy.", "properties": { "agent_type": { "title": "Agent Type", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "version": { "title": "Version", "type": "string" } }, "required": [ "version", "agent_type" ], "title": "PolicyRollbackRequest", "type": "object" }, "PolicyStatus": { "description": "Policy deployment status.", "enum": [ "training", "candidate", "canary", "production", "rollback", "archived" ], "title": "PolicyStatus", "type": "string" }, "PolicyStatusResponse": { "description": "Comprehensive policy status.", "properties": { "agent_type": { "title": "Agent Type", "type": "string" }, "canary": { "anyOf": [ { "$ref": "#/components/schemas/PolicyVersion" }, { "type": "null" } ] }, "latest_candidate": { "anyOf": [ { "$ref": "#/components/schemas/PolicyVersion" }, { "type": "null" } ] }, "production": { "anyOf": [ { "$ref": "#/components/schemas/PolicyVersion" }, { "type": "null" } ] }, "recent_versions": { "default": [], "items": { "$ref": "#/components/schemas/PolicyVersion" }, "title": "Recent Versions", "type": "array" }, "total_versions": { "title": "Total Versions", "type": "integer" } }, "required": [ "agent_type", "total_versions" ], "title": "PolicyStatusResponse", "type": "object" }, "PolicyVersion": { "description": "Policy version metadata.", "properties": { "agent_type": { "title": "Agent Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "metrics": { "additionalProperties": true, "default": {}, "title": "Metrics", "type": "object" }, "promoted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Promoted At" }, "status": { "$ref": "#/components/schemas/PolicyStatus" }, "version": { "title": "Version", "type": "string" } }, "required": [ "id", "version", "status", "agent_type", "created_at" ], "title": "PolicyVersion", "type": "object" }, "PowChallengeResponse": { "properties": { "algorithm": { "default": "sha256(challenge:nonce) has >= difficulty_bits leading zero bits", "title": "Algorithm", "type": "string" }, "challenge": { "title": "Challenge", "type": "string" }, "difficulty_bits": { "title": "Difficulty Bits", "type": "integer" }, "ttl_seconds": { "title": "Ttl Seconds", "type": "integer" } }, "required": [ "challenge", "difficulty_bits", "ttl_seconds" ], "title": "PowChallengeResponse", "type": "object" }, "ProcessingStatus": { "description": "Processing status.", "enum": [ "uploaded", "processing", "completed", "failed" ], "title": "ProcessingStatus", "type": "string" }, "ProfileRequest": { "additionalProperties": false, "description": "Profile retrieval request (similar to SuperMemory's POST /v4/profile).", "properties": { "app_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional collection filter for search", "title": "Collection Id" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional end-user scope (multi-tenant isolation)", "title": "End User Id" }, "include_dynamic": { "default": true, "description": "Include dynamic facts", "title": "Include Dynamic", "type": "boolean" }, "include_static": { "default": true, "description": "Include static facts", "title": "Include Static", "type": "boolean" }, "min_confidence": { "default": 0.0, "description": "Minimum confidence threshold", "maximum": 1.0, "minimum": 0.0, "title": "Min Confidence", "type": "number" }, "namespace": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "observer_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Optional observer/agent scope", "title": "Observer Id" }, "q": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional search query to combine with profile", "title": "Q" }, "search_limit": { "default": 10, "description": "Number of search results if query provided", "maximum": 100.0, "minimum": 1.0, "title": "Search Limit", "type": "integer" } }, "title": "ProfileRequest", "type": "object" }, "ProfileResponse": { "description": "Profile response.\n\nPDF contract asks for flat ``name`` / ``timezone`` / ``language`` fields\nat the top level. We populate them by extracting the matching facts from\nthe underlying bucket-based storage. The original ``profile`` envelope\nwith static / dynamic buckets is kept for backward compatibility with\nexisting clients (dashboard, dialectic reasoning, etc.).", "properties": { "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "profile": { "additionalProperties": true, "title": "Profile", "type": "object" }, "searchResults": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Searchresults" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" } }, "required": [ "profile", "metadata" ], "title": "ProfileResponse", "type": "object" }, "PromotionRequest": { "description": "Manual promotion trigger request.", "properties": { "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" } }, "title": "PromotionRequest", "type": "object" }, "PurchaseHistoryItem": { "description": "Token purchase history item.", "properties": { "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "pack_name": { "title": "Pack Name", "type": "string" }, "price_display": { "title": "Price Display", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tokens_amount": { "title": "Tokens Amount", "type": "integer" } }, "required": [ "id", "pack_name", "tokens_amount", "price_display", "status", "created_at" ], "title": "PurchaseHistoryItem", "type": "object" }, "PurchaseHistoryResponse": { "description": "Response with purchase history.", "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseHistoryItem" }, "title": "Purchases", "type": "array" }, "total_purchased": { "title": "Total Purchased", "type": "integer" } }, "required": [ "purchases", "total_purchased" ], "title": "PurchaseHistoryResponse", "type": "object" }, "PurchaseResponse": { "description": "Response with Stripe checkout URL.", "properties": { "checkout_url": { "title": "Checkout Url", "type": "string" }, "pack": { "$ref": "#/components/schemas/TokenPackInfo" }, "session_id": { "title": "Session Id", "type": "string" } }, "required": [ "checkout_url", "session_id", "pack" ], "title": "PurchaseResponse", "type": "object" }, "QualityAssessment": { "description": "Complete quality assessment for a memory.", "properties": { "assessment_time": { "format": "date-time", "title": "Assessment Time", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details" }, "memory_id": { "title": "Memory Id", "type": "string" }, "metrics": { "$ref": "#/components/schemas/QualityMetrics" }, "recommendations": { "items": { "type": "string" }, "title": "Recommendations", "type": "array" } }, "required": [ "memory_id", "metrics", "assessment_time" ], "title": "QualityAssessment", "type": "object" }, "QualityDistribution": { "description": "Distribution of memory quality across tiers (as percentages 0-1).", "properties": { "avg_quality_score": { "title": "Avg Quality Score", "type": "number" }, "excellent": { "title": "Excellent", "type": "number" }, "fair": { "title": "Fair", "type": "number" }, "good": { "title": "Good", "type": "number" }, "poor": { "title": "Poor", "type": "number" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "excellent", "good", "fair", "poor", "total", "avg_quality_score" ], "title": "QualityDistribution", "type": "object" }, "QualityMetrics": { "description": "Quality metrics for a memory.", "properties": { "content_quality": { "maximum": 1.0, "minimum": 0.0, "title": "Content Quality", "type": "number" }, "overall_score": { "description": "Overall quality score (0-1)", "maximum": 1.0, "minimum": 0.0, "title": "Overall Score", "type": "number" }, "quality_tier": { "description": "Quality tier (excellent/good/fair/poor)", "title": "Quality Tier", "type": "string" }, "retrieval_performance": { "maximum": 1.0, "minimum": 0.0, "title": "Retrieval Performance", "type": "number" }, "temporal_relevance": { "maximum": 1.0, "minimum": 0.0, "title": "Temporal Relevance", "type": "number" }, "user_engagement": { "maximum": 1.0, "minimum": 0.0, "title": "User Engagement", "type": "number" } }, "required": [ "overall_score", "content_quality", "retrieval_performance", "temporal_relevance", "user_engagement", "quality_tier" ], "title": "QualityMetrics", "type": "object" }, "QueryAtTimeRequest": { "description": "Request model for point-in-time queries.", "properties": { "predicate": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Predicate" }, "subject": { "maxLength": 512, "minLength": 1, "title": "Subject", "type": "string" }, "timestamp": { "format": "date-time", "title": "Timestamp", "type": "string" } }, "required": [ "subject", "timestamp" ], "title": "QueryAtTimeRequest", "type": "object" }, "QuotaUsage": { "description": "Usage info for a single quota type.", "properties": { "limit": { "description": "Maximum allowed (-1 for unlimited)", "title": "Limit", "type": "integer" }, "percentage": { "description": "Percentage used (0-100)", "title": "Percentage", "type": "number" }, "remaining": { "description": "Amount remaining (-1 for unlimited)", "title": "Remaining", "type": "integer" }, "used": { "description": "Amount used", "title": "Used", "type": "integer" } }, "required": [ "used", "limit", "remaining", "percentage" ], "title": "QuotaUsage", "type": "object" }, "RLRerankingToggle": { "description": "Per-collection opt-in for the trained RL reranker.", "properties": { "enabled": { "description": "Enable/disable the RL reranker for this collection", "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "RLRerankingToggle", "type": "object" }, "RankingFeedbackRequest": { "description": "Request for ranking correction feedback.", "properties": { "actual_rank": { "description": "Position where memory appeared", "title": "Actual Rank", "type": "integer" }, "expected_rank": { "description": "Where it should have been", "title": "Expected Rank", "type": "integer" }, "memory_id": { "description": "Memory ID with ranking issue (accepts `id` / `source_memory_id`).", "title": "Memory Id", "type": "string" }, "query": { "description": "Original search query", "title": "Query", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason for correction", "title": "Reason" } }, "required": [ "memory_id", "query", "actual_rank", "expected_rank" ], "title": "RankingFeedbackRequest", "type": "object" }, "ReasoningRequest": { "description": "Reasoning request schema.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "facets": { "description": "Optional typed external decomposition facets.", "items": { "type": "string" }, "maxItems": 64, "title": "Facets", "type": "array" }, "include_steps": { "default": false, "title": "Include Steps", "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "query": { "description": "Reasoning query (cannot be empty or whitespace-only)", "minLength": 1, "title": "Query", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "query" ], "title": "ReasoningRequest", "type": "object" }, "ReasoningResponse": { "description": "Reasoning response schema.", "properties": { "abstain_recommended": { "default": false, "title": "Abstain Recommended", "type": "boolean" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer" }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/backend__api__v1__endpoints__search__BillingInfo" }, { "type": "null" } ] }, "degraded": { "default": false, "title": "Degraded", "type": "boolean" }, "evidence_claims": { "items": { "additionalProperties": true, "type": "object" }, "title": "Evidence Claims", "type": "array" }, "evidence_ids": { "items": { "type": "string" }, "title": "Evidence Ids", "type": "array" }, "grounding": { "additionalProperties": true, "title": "Grounding", "type": "object" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "no_match": { "default": false, "title": "No Match", "type": "boolean" }, "query_confidence": { "default": 0.0, "maximum": 1.0, "minimum": 0.0, "title": "Query Confidence", "type": "number" }, "reasoning_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reasoning Context" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "safety_contract_version": { "default": "search-safety-v1", "title": "Safety Contract Version", "type": "string" }, "sources": { "items": { "additionalProperties": true, "type": "object" }, "title": "Sources", "type": "array" } }, "required": [ "answer", "sources", "metadata" ], "title": "ReasoningResponse", "type": "object" }, "RecentRequest": { "description": "A recent API request.", "properties": { "api_key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Prefix" }, "endpoint": { "title": "Endpoint", "type": "string" }, "id": { "title": "Id", "type": "string" }, "latency_ms": { "title": "Latency Ms", "type": "number" }, "method": { "title": "Method", "type": "string" }, "status_code": { "title": "Status Code", "type": "integer" }, "timestamp": { "format": "date-time", "title": "Timestamp", "type": "string" } }, "required": [ "id", "endpoint", "method", "status_code", "latency_ms", "timestamp", "api_key_prefix" ], "title": "RecentRequest", "type": "object" }, "RefreshTokenRequest": { "description": "Refresh token request schema.", "properties": { "refresh_token": { "title": "Refresh Token", "type": "string" } }, "required": [ "refresh_token" ], "title": "RefreshTokenRequest", "type": "object" }, "RelevanceFeedbackRequest": { "description": "Request for relevance feedback.", "properties": { "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional user comment", "title": "Comment" }, "is_relevant": { "description": "Whether memory was relevant (accepts `relevant` as an alias).", "title": "Is Relevant", "type": "boolean" }, "memory_id": { "description": "Memory ID being rated (accepts `id` / `source_memory_id`).", "title": "Memory Id", "type": "string" }, "query": { "description": "Original search query", "title": "Query", "type": "string" } }, "required": [ "memory_id", "query", "is_relevant" ], "title": "RelevanceFeedbackRequest", "type": "object" }, "ReplaceMemoryRequest": { "description": "Request model for replacing memory content.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "memory_id": { "title": "Memory Id", "type": "string" }, "new_content": { "title": "New Content", "type": "string" }, "old_content": { "title": "Old Content", "type": "string" } }, "required": [ "memory_id", "old_content", "new_content", "collection_id" ], "title": "ReplaceMemoryRequest", "type": "object" }, "ResetPasswordRequest": { "description": "Reset password request schema - uses verified token.", "properties": { "new_password": { "title": "New Password", "type": "string" }, "reset_token": { "title": "Reset Token", "type": "string" } }, "required": [ "reset_token", "new_password" ], "title": "ResetPasswordRequest", "type": "object" }, "ResetPasswordResponse": { "description": "Reset password response schema.", "properties": { "message": { "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "ResetPasswordResponse", "type": "object" }, "RethinkMemoryRequest": { "description": "Request model for rethinking memory.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "memory_id": { "title": "Memory Id", "type": "string" } }, "required": [ "memory_id", "collection_id" ], "title": "RethinkMemoryRequest", "type": "object" }, "SearchRequest": { "additionalProperties": false, "description": "Search request schema.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "debug": { "default": false, "title": "Debug", "type": "boolean" }, "debug_memory_ids": { "description": "Optional memory UUIDs to trace through authenticated debug search. Only rows visible in the request's canonical tenant scope are inspected.", "items": { "type": "string" }, "maxItems": 10, "title": "Debug Memory Ids", "type": "array" }, "facets": { "description": "Optional first-class atomic subqueries supplied by an external planner. Hebbrix preserves an independent candidate pool and coverage provenance for every facet before global ranking.", "items": { "type": "string" }, "maxItems": 64, "title": "Facets", "type": "array" }, "fast": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Fast" }, "filters": { "additionalProperties": true, "default": {}, "title": "Filters", "type": "object" }, "grounding": { "default": "soft", "description": "Claim-grounding policy: off bypasses claim filtering, soft applies semantic-equivalence grounding and reports confidence, and strict requires a verified subject-and-predicate match.", "enum": [ "off", "soft", "strict" ], "title": "Grounding", "type": "string" }, "group_by_source": { "default": true, "title": "Group By Source", "type": "boolean" }, "include_explanations": { "default": false, "title": "Include Explanations", "type": "boolean" }, "include_low_confidence": { "default": false, "title": "Include Low Confidence", "type": "boolean" }, "include_metadata": { "default": true, "title": "Include Metadata", "type": "boolean" }, "include_superseded": { "default": false, "title": "Include Superseded", "type": "boolean" }, "limit": { "default": 10, "description": "Number of results (1-100)", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "max_per_source": { "default": 1, "description": "Chunks to keep per source when group_by_source collapses (default 1). Raise to retrieve full multi-step procedures/runbooks whose later steps would otherwise be collapsed away.", "maximum": 50.0, "minimum": 1.0, "title": "Max Per Source", "type": "integer" }, "min_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Alias for `threshold` \u2014 minimum relevance score (0.0\u20131.0). Applied as an absolute probability when score_calibrated=true, otherwise as a fraction of the strongest fused result.", "title": "Min Score" }, "query": { "description": "Search query (cannot be empty)", "minLength": 1, "title": "Query", "type": "string" }, "recall_mode": { "default": false, "title": "Recall Mode", "type": "boolean" }, "require_collection_id": { "default": false, "title": "Require Collection Id", "type": "boolean" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "search_type": { "default": "hybrid", "enum": [ "hybrid", "vector", "bm25", "graph" ], "title": "Search Type", "type": "string" }, "temporal_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Temporal Mode" }, "threshold": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Minimum relevance score (0.0\u20131.0)", "title": "Threshold" }, "use_enhanced": { "default": false, "title": "Use Enhanced", "type": "boolean" }, "use_feedback_boost": { "default": true, "title": "Use Feedback Boost", "type": "boolean" }, "use_outcome_boost": { "default": true, "title": "Use Outcome Boost", "type": "boolean" }, "use_rl_ranking": { "default": false, "title": "Use Rl Ranking", "type": "boolean" }, "use_rl_reranking": { "default": false, "title": "Use Rl Reranking", "type": "boolean" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "required": [ "query" ], "title": "SearchRequest", "type": "object" }, "SearchResponse": { "description": "Search response schema.", "properties": { "abstain_recommended": { "default": false, "description": "True when an agent should abstain instead of treating nearest-neighbor padding as evidence.", "title": "Abstain Recommended", "type": "boolean" }, "cache_hit": { "default": false, "title": "Cache Hit", "type": "boolean" }, "candidate_coverage": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Candidate Coverage" }, "confidence_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "calibrated_match, direct_lexical_match, no_confident_match, no_candidates, calibration_unavailable, or claim_not_grounded", "title": "Confidence Reason" }, "coverage_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "complete, incomplete, or unavailable for the selected top-k set", "title": "Coverage Status" }, "debug": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Debug" }, "degraded": { "default": false, "title": "Degraded", "type": "boolean" }, "degraded_sources": { "items": { "type": "string" }, "title": "Degraded Sources", "type": "array" }, "estimated_facet_coverage": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Estimated fraction of planned atomic facets represented in the stable coverage prefix. This set-level estimate does not require per-document neural score calibration; null for non-compound search.", "title": "Estimated Facet Coverage" }, "evidence_claims": { "description": "Claim receipts for each evidence ID, including the requested predicate/attribute and grounding status when available.", "items": { "additionalProperties": true, "type": "object" }, "title": "Evidence Claims", "type": "array" }, "evidence_ids": { "description": "Ordered IDs of response rows that may be used as evidence. Empty whenever abstention is recommended.", "items": { "type": "string" }, "title": "Evidence Ids", "type": "array" }, "facet_evidence": { "description": "Proof-backed mapping from every required facet to the memory IDs that remain in the final returned result set. A facet is satisfied only when its required certified witnesses survived final truncation.", "items": { "additionalProperties": true, "type": "object" }, "title": "Facet Evidence", "type": "array" }, "feedback_reranking_applied": { "default": false, "title": "Feedback Reranking Applied", "type": "boolean" }, "grounding": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Subject-and-predicate evidence contract for a narrow entity-bound query. A no_grounded_match status means candidates were related to the entity but did not assert the requested attribute.", "title": "Grounding" }, "low_confidence_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Low Confidence Count" }, "most_recent_result_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Most Recent Result Index" }, "no_match": { "default": false, "description": "True when no candidate cleared the evidence confidence gate.", "title": "No Match", "type": "boolean" }, "oldest_result_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Oldest Result Index" }, "outcome_reranking_applied": { "default": false, "title": "Outcome Reranking Applied", "type": "boolean" }, "parse_confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Parse Confidence" }, "processing_time_ms": { "title": "Processing Time Ms", "type": "number" }, "proof_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Automatic tenant-bound ProofLoop context for creating a causal learning decision without reconstructing the retrieved evidence.", "title": "Proof Context" }, "query": { "title": "Query", "type": "string" }, "query_confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Set-level retrieval confidence. For compound requests this combines estimated facet coverage with the weakest per-facet calibration; for narrow requests it is the strongest calibrated result.", "title": "Query Confidence" }, "query_plan_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query Plan Version" }, "ranking_fallback_applied": { "default": false, "title": "Ranking Fallback Applied", "type": "boolean" }, "ranking_fallback_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ranking Fallback Reason" }, "ranking_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ranking Policy" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "reranker_applied": { "default": false, "title": "Reranker Applied", "type": "boolean" }, "reranker_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reranker Reason" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "title": "Results", "type": "array" }, "rl_policy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rl Policy Version" }, "rl_ranking_applied": { "default": false, "title": "Rl Ranking Applied", "type": "boolean" }, "rl_reranking_applied": { "default": false, "title": "Rl Reranking Applied", "type": "boolean" }, "safety_contract_version": { "default": "search-safety-v1", "description": "Version of the cross-surface fail-closed response contract.", "title": "Safety Contract Version", "type": "string" }, "scores_calibrated": { "default": false, "title": "Scores Calibrated", "type": "boolean" }, "search_type": { "title": "Search Type", "type": "string" }, "selected_coverage": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Selected Coverage" }, "task_contract": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Typed query-shape, requested-behavior, output-schema, and safety contract used by native Reason.", "title": "Task Contract" }, "total": { "title": "Total", "type": "integer" }, "total_before_dedup": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Before Dedup" } }, "required": [ "query", "results", "total", "search_type", "processing_time_ms" ], "title": "SearchResponse", "type": "object" }, "SearchResult": { "description": "Search result schema.", "properties": { "content": { "title": "Content", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "explanation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Explanation" }, "feedback_boost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Feedback Boost" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "importance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Importance" }, "low_confidence": { "default": false, "title": "Low Confidence", "type": "boolean" }, "memory_id": { "title": "Memory Id", "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "normalized_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Absolute 0\u20131 relevance probability (sigmoid of the cross-encoder logit), independent of the other results. THRESHOLD ON THIS as a confidence gate \u2014 recommended ~0.5. Null when the selected low-latency ranking policy did not run a calibration model.", "title": "Normalized Score" }, "outcome_boost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Outcome Boost" }, "policy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Version" }, "processing_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Processing Status" }, "rank": { "title": "Rank", "type": "integer" }, "rerank_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Rerank Score" }, "score": { "description": "Ranking score on the active policy's native scale. It is a calibrated relevance probability only when score_calibrated=true; otherwise it is a relative fusion score and must not be used as an absolute threshold.", "title": "Score", "type": "number" }, "score_calibrated": { "default": false, "description": "True only when score/normalized_score came from the calibrated relevance model; false for relative dense/sparse fusion scores.", "title": "Score Calibrated", "type": "boolean" }, "source": { "title": "Source", "type": "string" }, "source_memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Memory Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "memory_id", "content", "score", "rank", "source", "created_at", "updated_at" ], "title": "SearchResult", "type": "object" }, "SimpleMessage": { "description": "Simple message for conversation history.", "properties": { "content": { "title": "Content", "type": "string" }, "role": { "title": "Role", "type": "string" } }, "required": [ "role", "content" ], "title": "SimpleMessage", "type": "object" }, "Source": { "description": "Source document for answer.", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "source_file": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source File" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "Source", "type": "object" }, "StartersResponse": { "description": "Response containing multiple conversation starters.", "properties": { "count": { "title": "Count", "type": "integer" }, "starters": { "items": { "$ref": "#/components/schemas/ConversationStarter" }, "title": "Starters", "type": "array" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "starters", "count", "user_id" ], "title": "StartersResponse", "type": "object" }, "SubscriptionResponse": { "description": "User subscription details.", "properties": { "cancel_at_period_end": { "title": "Cancel At Period End", "type": "boolean" }, "canceled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Canceled At" }, "current_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Current Period End" }, "current_period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Current Period Start" }, "days_until_renewal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Until Renewal" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "plan_id": { "title": "Plan Id", "type": "string" }, "plan_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Name" }, "status": { "title": "Status", "type": "string" }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier" }, "trial_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Trial End" } }, "required": [ "id", "plan_id", "status", "is_active", "current_period_start", "current_period_end", "cancel_at_period_end", "canceled_at", "trial_end", "days_until_renewal" ], "title": "SubscriptionResponse", "type": "object" }, "SuggestedAction": { "description": "A suggested follow-up action.", "properties": { "action": { "description": "Suggested action name", "title": "Action", "type": "string" }, "description": { "description": "Why this action is suggested", "title": "Description", "type": "string" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Suggested parameters", "title": "Params" } }, "required": [ "action", "description" ], "title": "SuggestedAction", "type": "object" }, "SystemStatsResponse": { "description": "Current database counts, visible only to administrators.", "properties": { "generated_at": { "format": "date-time", "title": "Generated At", "type": "string" }, "total_collections": { "title": "Total Collections", "type": "integer" }, "total_memories": { "title": "Total Memories", "type": "integer" }, "total_users": { "title": "Total Users", "type": "integer" } }, "required": [ "total_memories", "total_collections", "total_users", "generated_at" ], "title": "SystemStatsResponse", "type": "object" }, "TemporalQueryRequest": { "description": "Temporal query request schema.", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "depth": { "anyOf": [ { "maximum": 5.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Depth" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" }, "enduser_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enduser Id" }, "entity": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Entity" }, "limit": { "default": 100, "maximum": 1000.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "query": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Query" }, "recorded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Recorded At" }, "relation_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relation Type" }, "timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Timestamp" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "title": "TemporalQueryRequest", "type": "object" }, "TicketResponse": { "properties": { "category": { "title": "Category", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "customer_email": { "title": "Customer Email", "type": "string" }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Name" }, "description": { "title": "Description", "type": "string" }, "hubspot_deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hubspot Deal Id" }, "id": { "title": "Id", "type": "string" }, "priority": { "title": "Priority", "type": "string" }, "resolved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved At" }, "status": { "title": "Status", "type": "string" }, "subject": { "title": "Subject", "type": "string" } }, "required": [ "id", "subject", "description", "category", "priority", "status", "customer_email", "customer_name", "hubspot_deal_id", "created_at", "resolved_at" ], "title": "TicketResponse", "type": "object" }, "TierConfigResponse": { "description": "Tier configuration response.", "properties": { "consolidation_enabled": { "title": "Consolidation Enabled", "type": "integer" }, "consolidation_min_cluster_size": { "title": "Consolidation Min Cluster Size", "type": "integer" }, "consolidation_similarity_threshold": { "title": "Consolidation Similarity Threshold", "type": "number" }, "lpm_min_importance": { "title": "Lpm Min Importance", "type": "number" }, "mtm_consolidation_interval_seconds": { "title": "Mtm Consolidation Interval Seconds", "type": "integer" }, "mtm_to_lpm_importance_threshold": { "title": "Mtm To Lpm Importance Threshold", "type": "number" }, "stm_max_age_seconds": { "title": "Stm Max Age Seconds", "type": "integer" }, "stm_max_items": { "title": "Stm Max Items", "type": "integer" }, "stm_to_mtm_access_threshold": { "title": "Stm To Mtm Access Threshold", "type": "integer" }, "stm_to_mtm_importance_threshold": { "title": "Stm To Mtm Importance Threshold", "type": "number" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "stm_max_age_seconds", "stm_max_items", "stm_to_mtm_access_threshold", "stm_to_mtm_importance_threshold", "mtm_consolidation_interval_seconds", "mtm_to_lpm_importance_threshold", "lpm_min_importance", "consolidation_enabled", "consolidation_similarity_threshold", "consolidation_min_cluster_size" ], "title": "TierConfigResponse", "type": "object" }, "TierConfigUpdate": { "description": "Tier configuration update schema.", "properties": { "consolidation_min_cluster_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Consolidation Min Cluster Size" }, "consolidation_similarity_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Consolidation Similarity Threshold" }, "enable_automatic_consolidation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Automatic Consolidation" }, "lpm_min_importance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lpm Min Importance" }, "mtm_consolidation_interval_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Mtm Consolidation Interval Seconds" }, "mtm_to_lpm_importance_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mtm To Lpm Importance Threshold" }, "stm_max_age_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stm Max Age Seconds" }, "stm_max_items": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stm Max Items" }, "stm_to_mtm_access_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stm To Mtm Access Threshold" }, "stm_to_mtm_importance_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Stm To Mtm Importance Threshold" } }, "title": "TierConfigUpdate", "type": "object" }, "TierStatsResponse": { "description": "Tier statistics response.", "properties": { "avg_lpm_strength": { "title": "Avg Lpm Strength", "type": "number" }, "avg_mtm_strength": { "title": "Avg Mtm Strength", "type": "number" }, "avg_stm_strength": { "title": "Avg Stm Strength", "type": "number" }, "lpm_count": { "title": "Lpm Count", "type": "integer" }, "mtm_count": { "title": "Mtm Count", "type": "integer" }, "recent_consolidations": { "title": "Recent Consolidations", "type": "integer" }, "recent_demotions": { "title": "Recent Demotions", "type": "integer" }, "recent_promotions": { "title": "Recent Promotions", "type": "integer" }, "stm_count": { "title": "Stm Count", "type": "integer" }, "total_count": { "title": "Total Count", "type": "integer" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "stm_count", "mtm_count", "lpm_count", "total_count", "avg_stm_strength", "avg_mtm_strength", "avg_lpm_strength", "recent_promotions", "recent_demotions", "recent_consolidations" ], "title": "TierStatsResponse", "type": "object" }, "TieredMemoryResponse": { "description": "Tiered memory response.", "properties": { "access_count": { "title": "Access Count", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "current_strength": { "title": "Current Strength", "type": "number" }, "id": { "title": "Id", "type": "string" }, "importance_score": { "title": "Importance Score", "type": "number" }, "last_accessed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Accessed At" }, "memory_id": { "title": "Memory Id", "type": "string" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "id", "memory_id", "tier", "current_strength", "access_count", "importance_score", "last_accessed_at", "created_at" ], "title": "TieredMemoryResponse", "type": "object" }, "TokenPackInfo": { "description": "Information about a token pack.", "properties": { "id": { "title": "Id", "type": "string" }, "price_cents": { "title": "Price Cents", "type": "integer" }, "price_display": { "title": "Price Display", "type": "string" }, "rate_per_million": { "title": "Rate Per Million", "type": "string" }, "tokens": { "title": "Tokens", "type": "integer" } }, "required": [ "id", "tokens", "price_cents", "price_display", "rate_per_million" ], "title": "TokenPackInfo", "type": "object" }, "TokenPacksResponse": { "description": "Response with available token packs.", "properties": { "can_purchase": { "title": "Can Purchase", "type": "boolean" }, "current_balance": { "title": "Current Balance", "type": "integer" }, "packs": { "items": { "$ref": "#/components/schemas/TokenPackInfo" }, "title": "Packs", "type": "array" }, "upgrade_required": { "title": "Upgrade Required", "type": "boolean" }, "upgrade_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upgrade Url" } }, "required": [ "packs", "current_balance", "can_purchase", "upgrade_required" ], "title": "TokenPacksResponse", "type": "object" }, "TokenQuotaInfo": { "description": "Token quota details with billing transparency.", "properties": { "purchased_remaining": { "description": "Purchased tokens remaining", "title": "Purchased Remaining", "type": "integer" }, "purchased_total": { "description": "Total purchased tokens (don't expire monthly)", "title": "Purchased Total", "type": "integer" }, "purchased_used": { "description": "Purchased tokens used", "title": "Purchased Used", "type": "integer" }, "reset_date": { "description": "When subscription quota resets (ISO format)", "title": "Reset Date", "type": "string" }, "subscription_limit": { "description": "Monthly token limit from subscription (-1 = unlimited)", "title": "Subscription Limit", "type": "integer" }, "subscription_remaining": { "description": "Tokens remaining from subscription (-1 = unlimited)", "title": "Subscription Remaining", "type": "integer" }, "subscription_used": { "description": "Tokens used from subscription this month", "title": "Subscription Used", "type": "integer" }, "total_remaining": { "description": "Total tokens available (subscription + purchased, -1 = unlimited)", "title": "Total Remaining", "type": "integer" } }, "required": [ "subscription_limit", "subscription_used", "subscription_remaining", "purchased_total", "purchased_used", "purchased_remaining", "total_remaining", "reset_date" ], "title": "TokenQuotaInfo", "type": "object" }, "TokenResponse": { "description": "Token response schema.", "properties": { "access_token": { "title": "Access Token", "type": "string" }, "expires_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires In" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "token_type": { "default": "bearer", "title": "Token Type", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "access_token", "user_id" ], "title": "TokenResponse", "type": "object" }, "ToolInfo": { "description": "Information about a single tool.", "properties": { "category": { "title": "Category", "type": "string" }, "description": { "title": "Description", "type": "string" }, "examples": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Examples", "type": "array" }, "is_destructive": { "title": "Is Destructive", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" }, "requires_auth": { "title": "Requires Auth", "type": "boolean" } }, "required": [ "name", "description", "category", "requires_auth", "is_destructive" ], "title": "ToolInfo", "type": "object" }, "ToolsResponse": { "description": "Response for tool discovery endpoint.", "properties": { "categories": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Categories", "type": "object" }, "tools": { "items": { "$ref": "#/components/schemas/ToolInfo" }, "title": "Tools", "type": "array" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "tools", "categories", "total_count" ], "title": "ToolsResponse", "type": "object" }, "TrackCodeChangeRequest": { "description": "Request to track a code change.", "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of agent making change", "title": "Agent Name" }, "branch_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Git branch name", "title": "Branch Name" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection ID for memories", "title": "Collection Id" }, "commit_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Git commit hash", "title": "Commit Hash" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of change", "title": "Description" }, "diff": { "description": "Git diff or code change", "title": "Diff", "type": "string" }, "file_path": { "description": "Path to file modified", "title": "File Path", "type": "string" }, "function_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Function/method modified", "title": "Function Name" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Programming language", "title": "Language" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "title": "Metadata", "type": "object" }, "task_type": { "default": "feature", "description": "Type of task (feature, bug_fix, refactor, test)", "title": "Task Type", "type": "string" } }, "required": [ "file_path", "diff" ], "title": "TrackCodeChangeRequest", "type": "object" }, "TrackErrorRequest": { "description": "Request to track an error.", "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent that encountered error", "title": "Agent Name" }, "code_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Code around the error", "title": "Code Context" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection ID for memories", "title": "Collection Id" }, "error_message": { "description": "Error message", "title": "Error Message", "type": "string" }, "error_type": { "description": "Type of error", "title": "Error Type", "type": "string" }, "file_path": { "description": "File where error occurred", "title": "File Path", "type": "string" }, "function_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Function where error occurred", "title": "Function Name" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Programming language", "title": "Language" }, "stack_trace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full stack trace", "title": "Stack Trace" } }, "required": [ "error_message", "error_type", "file_path" ], "title": "TrackErrorRequest", "type": "object" }, "TrackFixRequest": { "description": "Request to track a fix.", "properties": { "code_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Code after fix", "title": "Code After" }, "code_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Code before fix", "title": "Code Before" }, "coding_task_id": { "description": "ID of the coding task being fixed", "title": "Coding Task Id", "type": "string" }, "fix_description": { "description": "Description of the fix", "title": "Fix Description", "type": "string" }, "fix_strategy": { "description": "Strategy used (e.g., added_null_check)", "title": "Fix Strategy", "type": "string" }, "tests_passed": { "default": false, "description": "Whether tests pass after fix", "title": "Tests Passed", "type": "boolean" }, "time_to_fix_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Time taken to fix", "title": "Time To Fix Seconds" }, "was_successful": { "default": true, "description": "Whether fix resolved the issue", "title": "Was Successful", "type": "boolean" } }, "required": [ "coding_task_id", "fix_description", "fix_strategy" ], "title": "TrackFixRequest", "type": "object" }, "TrainPolicyRequest": { "description": "Request to trigger RL policy training.", "properties": { "agent_type": { "default": "memory_manager", "title": "Agent Type", "type": "string" }, "force": { "default": false, "title": "Force", "type": "boolean" }, "min_interactions": { "default": 100, "title": "Min Interactions", "type": "integer" } }, "title": "TrainPolicyRequest", "type": "object" }, "TrainingRequest": { "description": "Request model for training.", "properties": { "num_episodes": { "default": 100, "maximum": 10000.0, "minimum": 1.0, "title": "Num Episodes", "type": "integer" }, "num_epochs": { "default": 10, "maximum": 100.0, "minimum": 1.0, "title": "Num Epochs", "type": "integer" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "title": "TrainingRequest", "type": "object" }, "TransitionResponse": { "description": "Tier transition response.\n\nAliased to match the SQLAlchemy ``MemoryTierTransition`` model field\nnames (``transition_reason``, ``transition_metadata``). The previous\nschema used ``reason`` / ``metadata`` which don't exist on the model,\ncausing ``model_validate(t)`` to fail with two missing-field errors and\nevery ``GET /v1/tiers/transitions`` call to 500.", "properties": { "from_tier": { "title": "From Tier", "type": "string" }, "tiered_memory_id": { "title": "Tiered Memory Id", "type": "string" }, "to_tier": { "title": "To Tier", "type": "string" }, "transition_metadata": { "additionalProperties": true, "title": "Transition Metadata", "type": "object" }, "transition_reason": { "title": "Transition Reason", "type": "string" }, "transitioned_at": { "format": "date-time", "title": "Transitioned At", "type": "string" } }, "required": [ "tiered_memory_id", "from_tier", "to_tier", "transition_reason", "transitioned_at" ], "title": "TransitionResponse", "type": "object" }, "URLImportRequest": { "description": "URL import request.", "properties": { "collection_id": { "anyOf": [ { "maxLength": 36, "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "create_memories": { "default": true, "title": "Create Memories", "type": "boolean" }, "url": { "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "URLImportRequest", "type": "object" }, "URLSourceType": { "description": "Type of URL source.", "enum": [ "article", "twitter", "youtube", "generic" ], "title": "URLSourceType", "type": "string" }, "UnifiedFeedbackRequest": { "description": "Body for the convenience endpoint POST /v1/feedback.\n\nProvide ``type`` (relevance | ranking | missing), or omit it and the type is\ninferred from the fields present. For typed control use the dedicated\nsub-endpoints /v1/feedback/relevance, /ranking, /missing.", "properties": { "actual_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Observed rank. Type=ranking.", "title": "Actual Rank" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional comment", "title": "Comment" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Additional context (missing)", "title": "Context" }, "expected_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the missing memory. Type=missing.", "title": "Expected Content" }, "expected_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Expected rank. Type=ranking.", "title": "Expected Rank" }, "is_relevant": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Relevance verdict (accepts `relevant`). Type=relevance.", "title": "Is Relevant" }, "memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Memory ID (relevance/ranking). Accepts `id` / `source_memory_id`.", "title": "Memory Id" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original search query", "title": "Query" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason (ranking)", "title": "Reason" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "relevance | ranking | missing. Inferred from fields if omitted.", "title": "Type" } }, "title": "UnifiedFeedbackRequest", "type": "object" }, "UpdateProcedureRequest": { "description": "Mutable procedure fields; ownership and retrieval scope are immutable.", "properties": { "action": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Action" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "condition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Condition" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Parameters" } }, "title": "UpdateProcedureRequest", "type": "object" }, "UpdateTicketRequest": { "properties": { "resolution_notes": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "title": "Resolution Notes" }, "status": { "enum": [ "open", "in_progress", "waiting_on_customer", "resolved", "closed" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "UpdateTicketRequest", "type": "object" }, "Usage": { "description": "Token usage statistics.", "properties": { "completion_tokens": { "title": "Completion Tokens", "type": "integer" }, "prompt_tokens": { "title": "Prompt Tokens", "type": "integer" }, "total_tokens": { "title": "Total Tokens", "type": "integer" } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "title": "Usage", "type": "object" }, "UsageOverview": { "description": "Complete usage overview for the dashboard.\n\nRetains the legacy ``summary`` / ``api_keys`` / ``top_endpoints`` /\n``daily_usage`` layout. Adds PDF-contract ``api_calls`` object at the\ntop level (derived from the same counters) so contract-conformant\nclients can read ``api_calls.used`` / ``api_calls.limit`` directly.", "properties": { "api_calls": { "anyOf": [ { "$ref": "#/components/schemas/APICallsQuota" }, { "type": "null" } ] }, "api_keys": { "items": { "$ref": "#/components/schemas/APIKeyUsage" }, "title": "Api Keys", "type": "array" }, "daily_usage": { "items": { "$ref": "#/components/schemas/DailyUsage" }, "title": "Daily Usage", "type": "array" }, "summary": { "$ref": "#/components/schemas/UsageSummary" }, "top_endpoints": { "items": { "$ref": "#/components/schemas/EndpointUsage" }, "title": "Top Endpoints", "type": "array" } }, "required": [ "summary", "api_keys", "top_endpoints", "daily_usage" ], "title": "UsageOverview", "type": "object" }, "UsageQuotaResponse": { "description": "Complete usage quota information for the current user.", "properties": { "api_calls": { "$ref": "#/components/schemas/QuotaUsage", "description": "API calls quota usage" }, "chat_completions": { "$ref": "#/components/schemas/EndpointBreakdown", "description": "Chat completion requests this month" }, "credits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Credit usage (when credit billing is enabled)", "title": "Credits" }, "memories": { "$ref": "#/components/schemas/QuotaUsage", "description": "Memory quota usage" }, "period_end": { "description": "End of billing period", "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "description": "Start of billing period", "format": "date-time", "title": "Period Start", "type": "string" }, "searches": { "$ref": "#/components/schemas/EndpointBreakdown", "description": "Search requests this month" }, "tier": { "description": "Current subscription tier", "title": "Tier", "type": "string" }, "tokens": { "anyOf": [ { "$ref": "#/components/schemas/QuotaUsage" }, { "type": "null" } ], "description": "Legacy token quota (only when credit billing is disabled)" } }, "required": [ "tier", "memories", "api_calls", "searches", "chat_completions", "period_start", "period_end" ], "title": "UsageQuotaResponse", "type": "object" }, "UsageResponse": { "description": "Current usage statistics.", "properties": { "api_calls": { "additionalProperties": true, "title": "Api Calls", "type": "object" }, "has_overage": { "title": "Has Overage", "type": "boolean" }, "memories": { "additionalProperties": true, "title": "Memories", "type": "object" }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Period End" }, "period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Period Start" }, "storage_bytes": { "title": "Storage Bytes", "type": "integer" }, "tokens": { "additionalProperties": true, "title": "Tokens", "type": "object" } }, "required": [ "period_start", "period_end", "memories", "api_calls", "tokens", "storage_bytes", "has_overage" ], "title": "UsageResponse", "type": "object" }, "UsageSummary": { "description": "Summary of API usage over a time period.", "properties": { "avg_latency_ms": { "description": "Average latency in milliseconds", "title": "Avg Latency Ms", "type": "number" }, "failed_requests": { "description": "Number of failed requests (4xx, 5xx)", "title": "Failed Requests", "type": "integer" }, "period_end": { "description": "End of the period", "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "description": "Start of the period", "format": "date-time", "title": "Period Start", "type": "string" }, "success_rate": { "description": "Success rate as percentage (0-100)", "title": "Success Rate", "type": "number" }, "successful_requests": { "description": "Number of successful requests (2xx)", "title": "Successful Requests", "type": "integer" }, "total_bytes_received": { "description": "Total bytes received from API", "title": "Total Bytes Received", "type": "integer" }, "total_bytes_sent": { "description": "Total bytes sent to API", "title": "Total Bytes Sent", "type": "integer" }, "total_requests": { "description": "Total number of API requests", "title": "Total Requests", "type": "integer" } }, "required": [ "total_requests", "successful_requests", "failed_requests", "success_rate", "total_bytes_sent", "total_bytes_received", "avg_latency_ms", "period_start", "period_end" ], "title": "UsageSummary", "type": "object" }, "UserInfoResponse": { "description": "User information response schema.", "properties": { "auth_provider": { "title": "Auth Provider", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "full_name": { "title": "Full Name", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "is_admin": { "title": "Is Admin", "type": "boolean" }, "is_verified": { "title": "Is Verified", "type": "boolean" }, "tier": { "title": "Tier", "type": "string" }, "user_type": { "default": "developer", "title": "User Type", "type": "string" } }, "required": [ "id", "email", "full_name", "is_active", "is_verified", "is_admin", "tier", "created_at", "auth_provider" ], "title": "UserInfoResponse", "type": "object" }, "UserLogin": { "description": "User login schema.", "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "password": { "title": "Password", "type": "string" } }, "required": [ "email", "password" ], "title": "UserLogin", "type": "object" }, "UserRegister": { "description": "User registration schema with password validation.\n\nEnforces password strength requirements for SOC 2 compliance (CC6.1).", "example": { "email": "user@example.com", "full_name": "John Doe", "password": "SecurePass123!", "user_type": "developer" }, "properties": { "email": { "description": "User email address", "format": "email", "title": "Email", "type": "string" }, "full_name": { "description": "User's full name", "maxLength": 100, "minLength": 1, "title": "Full Name", "type": "string" }, "password": { "description": "Password (12\u201315 chars + lower/upper/digit/symbol, or >=16 chars + >=2 classes; not in common-password deny list; must not contain the email local-part)", "maxLength": 128, "minLength": 12, "title": "Password", "type": "string" }, "user_type": { "default": "developer", "description": "User type: 'consumer' (Hebbrix App) or 'developer' (Memory API)", "enum": [ "consumer", "developer" ], "title": "User Type", "type": "string" } }, "required": [ "email", "password", "full_name" ], "title": "UserRegister", "type": "object" }, "UserResponse": { "description": "User response schema.", "properties": { "email": { "title": "Email", "type": "string" }, "full_name": { "title": "Full Name", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "is_admin": { "title": "Is Admin", "type": "boolean" }, "is_verified": { "title": "Is Verified", "type": "boolean" }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preferred Model" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "id", "email", "full_name", "is_active", "is_verified", "is_admin", "tier" ], "title": "UserResponse", "type": "object" }, "UserUpdate": { "description": "User update schema.", "properties": { "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name" } }, "title": "UserUpdate", "type": "object" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" }, "VerifyResetOTPRequest": { "description": "Verify password reset OTP schema.", "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "otp_code": { "title": "Otp Code", "type": "string" } }, "required": [ "email", "otp_code" ], "title": "VerifyResetOTPRequest", "type": "object" }, "VerifyResetOTPResponse": { "description": "Response after successful OTP verification.", "properties": { "message": { "title": "Message", "type": "string" }, "reset_token": { "title": "Reset Token", "type": "string" } }, "required": [ "message", "reset_token" ], "title": "VerifyResetOTPResponse", "type": "object" }, "VersionedArtifact": { "additionalProperties": false, "properties": { "digest": { "anyOf": [ { "pattern": "^(?:sha256:)?[0-9a-fA-F]{64}$", "type": "string" }, { "type": "null" } ], "title": "Digest" }, "name": { "maxLength": 160, "minLength": 1, "title": "Name", "type": "string" }, "version": { "maxLength": 160, "minLength": 1, "title": "Version", "type": "string" } }, "required": [ "name", "version" ], "title": "VersionedArtifact", "type": "object" }, "VisualizationRequest": { "description": "Request schema for graph visualization.", "properties": { "center_entity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Center Entity" }, "center_memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Center Memory Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "depth": { "default": 2, "maximum": 3.0, "minimum": 1.0, "title": "Depth", "type": "integer" }, "include_entities": { "default": true, "title": "Include Entities", "type": "boolean" }, "include_memories": { "default": true, "title": "Include Memories", "type": "boolean" }, "max_nodes": { "default": 50, "maximum": 200.0, "minimum": 1.0, "title": "Max Nodes", "type": "integer" } }, "title": "VisualizationRequest", "type": "object" }, "WaitlistJoinRequest": { "description": "Schema for joining the waitlist.", "properties": { "company": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Company name", "title": "Company" }, "email": { "description": "Email address", "format": "email", "title": "Email", "type": "string" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Full name", "title": "Name" }, "referral_source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "How they heard about us", "title": "Referral Source" }, "role": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Job role/title", "title": "Role" }, "use_case": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Intended use case", "title": "Use Case" } }, "required": [ "email" ], "title": "WaitlistJoinRequest", "type": "object" }, "WaitlistJoinResponse": { "description": "Response after joining the waitlist.", "properties": { "already_registered": { "default": false, "title": "Already Registered", "type": "boolean" }, "message": { "title": "Message", "type": "string" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Position" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "message" ], "title": "WaitlistJoinResponse", "type": "object" }, "WaitlistStatsResponse": { "description": "Public waitlist statistics.", "properties": { "recent_signups_24h": { "title": "Recent Signups 24H", "type": "integer" }, "total_signups": { "title": "Total Signups", "type": "integer" } }, "required": [ "total_signups", "recent_signups_24h" ], "title": "WaitlistStatsResponse", "type": "object" }, "WebCitationResponse": { "description": "Citation from web search.", "properties": { "end_index": { "title": "End Index", "type": "integer" }, "start_index": { "title": "Start Index", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "title", "start_index", "end_index" ], "title": "WebCitationResponse", "type": "object" }, "WebSearchRequest": { "additionalProperties": false, "description": "Request for web search with real-time internet access.", "properties": { "allowed_domains": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "title": "Allowed Domains" }, "conversation_history": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SimpleMessage" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "title": "Conversation History" }, "model": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": "gpt-4o-mini", "title": "Model" }, "query": { "maxLength": 2000, "minLength": 1, "title": "Query", "type": "string" }, "search_context_size": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "default": "medium", "title": "Search Context Size" }, "user_location": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "User Location" } }, "required": [ "query" ], "title": "WebSearchRequest", "type": "object" }, "WebSearchResponse": { "description": "Response from web search with citations.", "properties": { "answer": { "title": "Answer", "type": "string" }, "citations": { "items": { "$ref": "#/components/schemas/WebCitationResponse" }, "title": "Citations", "type": "array" }, "search_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Id" }, "sources": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": "Sources", "type": "array" } }, "required": [ "answer", "citations", "sources" ], "title": "WebSearchResponse", "type": "object" }, "WebhookCreate": { "description": "Request to create a webhook.", "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Events", "type": "array" }, "max_retries": { "default": 5, "maximum": 12.0, "minimum": 0.0, "title": "Max Retries", "type": "integer" }, "retry_on_failure": { "default": true, "title": "Retry On Failure", "type": "boolean" }, "timeout_seconds": { "default": 30, "maximum": 30.0, "minimum": 1.0, "title": "Timeout Seconds", "type": "integer" }, "url": { "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" }, "webhook_metadata": { "additionalProperties": true, "title": "Webhook Metadata", "type": "object" } }, "required": [ "url", "events" ], "title": "WebhookCreate", "type": "object" }, "WebhookFailureListResponse": { "properties": { "failures": { "items": { "$ref": "#/components/schemas/WebhookFailureResponse" }, "title": "Failures", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "failures", "total" ], "title": "WebhookFailureListResponse", "type": "object" }, "WebhookFailureReplayResponse": { "properties": { "detail_message": { "title": "Detail Message", "type": "string" }, "id": { "title": "Id", "type": "string" }, "new_status": { "title": "New Status", "type": "string" }, "replayed": { "title": "Replayed", "type": "boolean" } }, "required": [ "id", "replayed", "new_status", "detail_message" ], "title": "WebhookFailureReplayResponse", "type": "object" }, "WebhookFailureResponse": { "properties": { "attempt_count": { "title": "Attempt Count", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "event_type": { "title": "Event Type", "type": "string" }, "id": { "title": "Id", "type": "string" }, "idempotency_key": { "title": "Idempotency Key", "type": "string" }, "last_attempted_at": { "format": "date-time", "title": "Last Attempted At", "type": "string" }, "status": { "title": "Status", "type": "string" }, "webhook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Id" }, "webhook_url": { "title": "Webhook Url", "type": "string" } }, "required": [ "id", "webhook_id", "webhook_url", "event_type", "idempotency_key", "error_message", "attempt_count", "status", "last_attempted_at", "created_at" ], "title": "WebhookFailureResponse", "type": "object" }, "WebhookResponse": { "description": "Webhook response schema.\n\nExposes the HMAC secret under two keys for contract compatibility:\n- ``signing_secret`` (PDF contract, preferred)\n- ``secret`` (legacy \u2014 kept to avoid breaking existing integrations)\n\nDelivery statistics are exposed in two shapes for the same reason:\n- ``delivery_statistics`` (PDF contract, nested object)\n- flat ``total_deliveries`` / ``successful_deliveries`` / \u2026 (legacy)", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delivery_statistics": { "$ref": "#/components/schemas/DeliveryStatistics" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "items": { "type": "string" }, "title": "Events", "type": "array" }, "failed_deliveries": { "title": "Failed Deliveries", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "last_delivery_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Delivery At" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "last_failure_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Failure At" }, "last_success_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Success At" }, "max_retries": { "title": "Max Retries", "type": "integer" }, "retry_on_failure": { "title": "Retry On Failure", "type": "boolean" }, "secret": { "title": "Secret", "type": "string" }, "signing_secret": { "title": "Signing Secret", "type": "string" }, "success_rate": { "title": "Success Rate", "type": "number" }, "successful_deliveries": { "title": "Successful Deliveries", "type": "integer" }, "timeout_seconds": { "title": "Timeout Seconds", "type": "integer" }, "total_deliveries": { "title": "Total Deliveries", "type": "integer" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "events", "is_active", "secret", "signing_secret", "delivery_statistics", "total_deliveries", "successful_deliveries", "failed_deliveries", "success_rate", "last_delivery_at", "last_success_at", "last_failure_at", "last_error", "retry_on_failure", "max_retries", "timeout_seconds", "created_at", "updated_at" ], "title": "WebhookResponse", "type": "object" }, "WebhookSecretRotateResponse": { "description": "Webhook secret rotation response.", "properties": { "id": { "title": "Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "rotated_at": { "format": "date-time", "title": "Rotated At", "type": "string" }, "secret": { "title": "Secret", "type": "string" } }, "required": [ "id", "secret", "rotated_at", "message" ], "title": "WebhookSecretRotateResponse", "type": "object" }, "WebhookTestResponse": { "description": "Webhook test response.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "message": { "title": "Message", "type": "string" }, "response_time_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Response Time Ms" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "message" ], "title": "WebhookTestResponse", "type": "object" }, "WebhookUpdate": { "description": "Request to update a webhook.", "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" }, { "type": "null" } ], "title": "Events" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "max_retries": { "anyOf": [ { "maximum": 12.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Max Retries" }, "retry_on_failure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Retry On Failure" }, "timeout_seconds": { "anyOf": [ { "maximum": 30.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Timeout Seconds" }, "url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Url" }, "webhook_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Webhook Metadata" } }, "title": "WebhookUpdate", "type": "object" }, "WorkingRepresentationRequest": { "additionalProperties": false, "description": "Request for working representation (compact user context).", "properties": { "app_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the representation to one owned collection", "title": "Collection Id" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the representation to one external end-user", "title": "End User Id" }, "max_facts": { "default": 20, "description": "Maximum facts to include", "maximum": 50.0, "minimum": 1.0, "title": "Max Facts", "type": "integer" }, "namespace": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" }, "observer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional observer/agent for scoped access", "title": "Observer Id" } }, "title": "WorkingRepresentationRequest", "type": "object" }, "backend__api__routes__consolidation__ConsolidateRequest": { "description": "Request model for memory consolidation.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "lookback_days": { "default": 7, "maximum": 365.0, "minimum": 1.0, "title": "Lookback Days", "type": "integer" }, "utility_threshold": { "default": 0.3, "maximum": 1.0, "minimum": 0.0, "title": "Utility Threshold", "type": "number" } }, "required": [ "collection_id" ], "title": "ConsolidateRequest", "type": "object" }, "backend__api__routes__temporal__AddFactRequest": { "description": "Request model for adding temporal fact.", "properties": { "confidence": { "default": 1.0, "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "object": { "maxLength": 512, "minLength": 1, "title": "Object", "type": "string" }, "object_type": { "default": "ENTITY", "maxLength": 128, "minLength": 1, "title": "Object Type", "type": "string" }, "observed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Observed At" }, "predicate": { "maxLength": 128, "minLength": 1, "title": "Predicate", "type": "string" }, "source_memory_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Source Memory Id" }, "subject": { "maxLength": 512, "minLength": 1, "title": "Subject", "type": "string" }, "subject_type": { "default": "ENTITY", "maxLength": 128, "minLength": 1, "title": "Subject Type", "type": "string" }, "valid_from": { "format": "date-time", "title": "Valid From", "type": "string" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Valid Until" } }, "required": [ "subject", "predicate", "object", "valid_from" ], "title": "AddFactRequest", "type": "object" }, "backend__api__routes__working_memory__ConsolidateRequest": { "description": "Request model for consolidating to long-term memory.", "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "importance_threshold": { "default": 0.5, "maximum": 1.0, "minimum": 0.0, "title": "Importance Threshold", "type": "number" }, "session_id": { "maxLength": 200, "minLength": 1, "title": "Session Id", "type": "string" } }, "required": [ "session_id", "collection_id" ], "title": "ConsolidateRequest", "type": "object" }, "backend__api__v1__endpoints__chat__BillingInfo": { "description": "Token billing transparency - shows exactly what user is charged.\n\nLike Gemini, we show users:\n- Actual tokens consumed\n- Model multiplier applied\n- Billed tokens (what they're charged)\n- Cost rates\n- Remaining quota", "example": { "actual_tokens": 1500, "billed_tokens": 1500, "cost_per_million_tokens": 19.0, "estimated_cost_usd": 0.0285, "model_used": "gpt-5-mini", "quota_remaining": 998500, "quota_reset_date": "2025-02-01T00:00:00", "token_multiplier": 1.0, "token_source": "subscription" }, "properties": { "actual_tokens": { "description": "Actual tokens from LLM API", "title": "Actual Tokens", "type": "integer" }, "billed_tokens": { "description": "Tokens charged to your quota (actual \u00d7 multiplier)", "title": "Billed Tokens", "type": "integer" }, "billing_mode": { "default": "legacy_token_quota", "description": "Billing policy applied: operation_credits or legacy_token_quota", "title": "Billing Mode", "type": "string" }, "cost_per_million_tokens": { "description": "Your effective rate per 1M tokens in USD", "title": "Cost Per Million Tokens", "type": "number" }, "estimated_cost_usd": { "description": "Estimated cost for this request in USD", "title": "Estimated Cost Usd", "type": "number" }, "model_used": { "description": "Actual model used (may differ from requested)", "title": "Model Used", "type": "string" }, "operation_credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Fixed operation credits charged for this request", "title": "Operation Credits Charged" }, "operation_credits_remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Operation credits remaining after this request", "title": "Operation Credits Remaining" }, "quota_remaining": { "description": "Tokens remaining after this request (-1 = unlimited)", "title": "Quota Remaining", "type": "integer" }, "quota_reset_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When subscription quota resets (ISO format)", "title": "Quota Reset Date" }, "token_multiplier": { "description": "Cost multiplier for this model (1.0 = baseline)", "title": "Token Multiplier", "type": "number" }, "token_source": { "description": "Token source used: 'subscription' or 'purchased'", "title": "Token Source", "type": "string" } }, "required": [ "model_used", "actual_tokens", "token_multiplier", "billed_tokens", "cost_per_million_tokens", "estimated_cost_usd", "token_source", "quota_remaining" ], "title": "BillingInfo", "type": "object" }, "backend__api__v1__endpoints__collections__BulkDeleteRequest": { "description": "Request body for bulk collection delete.", "properties": { "collection_ids": { "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Collection Ids", "type": "array" } }, "required": [ "collection_ids" ], "title": "BulkDeleteRequest", "type": "object" }, "backend__api__v1__endpoints__collections__BulkDeleteResponse": { "description": "Response for bulk delete operations.", "properties": { "deleted_count": { "title": "Deleted Count", "type": "integer" }, "dry_run": { "default": false, "title": "Dry Run", "type": "boolean" }, "errors": { "default": [], "items": { "type": "string" }, "title": "Errors", "type": "array" }, "failed_count": { "default": 0, "title": "Failed Count", "type": "integer" }, "would_delete": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Would Delete" } }, "required": [ "deleted_count" ], "title": "BulkDeleteResponse", "type": "object" }, "backend__api__v1__endpoints__memories__BulkDeleteRequest": { "description": "Request for bulk delete by IDs.\n\nAccepts either ``memory_ids`` (legacy) or ``ids`` (PDF contract). Both\nresolve to ``body.memory_ids`` internally so downstream code is\nunchanged.", "properties": { "memory_ids": { "description": "List of memory IDs to delete (max 500)", "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Memory Ids", "type": "array" } }, "required": [ "memory_ids" ], "title": "BulkDeleteRequest", "type": "object" }, "backend__api__v1__endpoints__memories__BulkDeleteResponse": { "description": "Response for bulk delete operations.", "properties": { "deleted_count": { "title": "Deleted Count", "type": "integer" }, "dry_run": { "default": false, "title": "Dry Run", "type": "boolean" }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "failed_count": { "default": 0, "title": "Failed Count", "type": "integer" }, "index_cleanup_pending": { "default": 0, "title": "Index Cleanup Pending", "type": "integer" }, "outbox_event_ids": { "items": { "type": "string" }, "title": "Outbox Event Ids", "type": "array" }, "would_delete": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Would Delete" } }, "required": [ "deleted_count" ], "title": "BulkDeleteResponse", "type": "object" }, "backend__api__v1__endpoints__profile__AddFactRequest": { "description": "Request to add/update a profile fact.", "properties": { "category": { "default": "other", "title": "Category", "type": "string" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope this fact to a collection (multi-tenant isolation). Omit for an account-wide fact.", "title": "Collection Id" }, "confidence": { "default": 0.9, "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "end_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope this fact to a single end-user (multi-tenant isolation). Omit for an account-wide fact.", "title": "End User Id" }, "fact_key": { "maxLength": 200, "minLength": 1, "title": "Fact Key", "type": "string" }, "fact_value": { "minLength": 1, "title": "Fact Value", "type": "string" }, "importance": { "default": 0.7, "maximum": 1.0, "minimum": 0.0, "title": "Importance", "type": "number" }, "profile_type": { "default": "static", "pattern": "^(static|dynamic)$", "title": "Profile Type", "type": "string" } }, "required": [ "fact_key", "fact_value" ], "title": "AddFactRequest", "type": "object" }, "backend__api__v1__endpoints__search__BillingInfo": { "description": "Token billing transparency - shows exactly what user is charged.\n\nLike Gemini, we show users:\n- Actual tokens consumed\n- Model multiplier applied\n- Billed tokens (what they're charged)\n- Cost rates\n- Remaining quota", "properties": { "actual_tokens": { "title": "Actual Tokens", "type": "integer" }, "billed_tokens": { "title": "Billed Tokens", "type": "integer" }, "cost_per_million_tokens": { "title": "Cost Per Million Tokens", "type": "number" }, "estimated_cost_usd": { "title": "Estimated Cost Usd", "type": "number" }, "model_used": { "title": "Model Used", "type": "string" }, "quota_remaining": { "title": "Quota Remaining", "type": "integer" }, "quota_reset_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quota Reset Date" }, "token_multiplier": { "title": "Token Multiplier", "type": "number" }, "token_source": { "title": "Token Source", "type": "string" } }, "required": [ "model_used", "actual_tokens", "token_multiplier", "billed_tokens", "cost_per_million_tokens", "estimated_cost_usd", "token_source", "quota_remaining" ], "title": "BillingInfo", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "scheme": "bearer", "type": "http" }, "StripeSignature": { "description": "Stripe webhook signature over the exact request body.", "in": "header", "name": "Stripe-Signature", "type": "apiKey" }, "TawkSignature": { "description": "HMAC-SHA1 signature over the exact webhook body.", "in": "header", "name": "X-Tawk-Signature", "type": "apiKey" } } }, "info": { "description": "Universal Memory API with Reinforcement Learning & Advanced Reasoning", "license": { "name": "Hebbrix Terms of Service", "url": "https://www.hebbrix.com/terms" }, "title": "AI Memory API", "version": "1.1.3", "x-hebbrix-build-header": "X-Hebbrix-Build", "x-hebbrix-contract": "public", "x-hebbrix-mcp-compatibility": { "migration_from_0.5.6": "none", "minimum": "0.5.5", "release_companion": "0.5.8", "safety_contract": "search-safety-v1", "tool_surface": 32 }, "x-hebbrix-release-traceability": { "api_compatibility": "The OpenAPI info.version is the public contract version, not the deployment build.", "changelog": "https://www.hebbrix.com/changelog", "compatibility_manifest": "GET /v1/release", "runtime_build": "Read X-Hebbrix-Build on every response and GET /v1/health." }, "x-hebbrix-sdk-compatibility": { "python": "2.4.1", "safety_contract": "search-safety-v1", "typescript": "2.3.1" }, "x-hebbrix-stability-levels": { "beta": "Public preview; may evolve with changelog notice.", "deprecated": "Scheduled for removal; inspect the operation description.", "ga": "Supported public contract; breaking changes require versioning.", "internal": "Not a customer contract." }, "x-hebbrix-version-header": "X-Hebbrix-Version" }, "openapi": "3.1.0", "paths": { "/": { "get": { "description": "Root endpoint with API information.", "operationId": "root__get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Root", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/benchmarks/locomo-2026-02.json": { "get": { "description": "Return the versioned public benchmark result with immutable caching.", "operationId": "get_locomo_2026_02_artifact_benchmarks_locomo_2026_02_json_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get the immutable February 2026 LoCoMo benchmark artifact", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/health": { "get": { "description": "Health check endpoint for load balancers and monitoring.", "operationId": "health_check_health_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Health Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/healthz": { "get": { "description": "Health check endpoint for load balancers and monitoring.", "operationId": "health_check_healthz_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Health Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/ready": { "get": { "description": "Verify dependencies required to accept traffic.\n\nOptional graph/scheduler degradation is reported but does not remove a\nhealthy API from service; durable queues and retrieval fallbacks continue\nto operate while those components recover.", "operationId": "readiness_check_ready_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Readiness Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/readyz": { "get": { "description": "Verify dependencies required to accept traffic.\n\nOptional graph/scheduler degradation is reported but does not remove a\nhealthy API from service; durable queues and retrieval fallbacks continue\nto operate while those components recover.", "operationId": "readiness_check_readyz_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Readiness Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/slo": { "get": { "description": "Backward-compatible alias for the versioned public SLO contract.", "operationId": "get_slo_metrics_slo_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Slo Metrics", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent": { "post": { "description": "Unified endpoint for all MemoryAI capabilities.\n\n AI agents can call this single endpoint with different actions to:\n - Search and retrieve memories\n - Create, update, delete memories\n - Process documents\n - Chat with memory context\n - Manage user profiles\n - Query knowledge graph\n - And more...\n\n Use GET /v1/agent/tools to discover all available actions.", "operationId": "execute_agent_action_v1_agent_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } }, "description": "Action executed successfully", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "description": "Invalid action or parameters" }, "401": { "description": "Authentication required" }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "description": "Action parameters failed validation" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Agent Action", "tags": [ "Agent" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent-signup": { "post": { "description": "Mint a shadow identity for an agent. No auth required \u2014 the caps are\nstructural (per-IP + global daily + kill switch), not reactive.", "operationId": "agent_signup_v1_agent_signup_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentSignupRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Agent Signup", "tags": [ "Agent Signup" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent-signup/challenge": { "post": { "description": "Issue a single-use proof-of-work challenge. Solving it (client-side,\n~1 second) lets the following /agent-signup call bypass the per-IP and\nper-subnet caps \u2014 so shared-IP / CGNAT users each mint once, while a farmer\npays CPU per account. Optional: signup without a challenge still works under\nthe standard IP caps.", "operationId": "agent_signup_challenge_v1_agent_signup_challenge_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowChallengeResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Agent Signup Challenge", "tags": [ "Agent Signup" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent-signup/claim": { "post": { "description": "Start claiming a shadow account (Tier 0 -> Tier 1): emails a 6-digit\ncode to the address. Same key, all memories carry over on verify.\n\nv1 restriction (deliberate): only a FRESH email \u2014 one with no existing\nHebbrix account \u2014 can claim. Attaching a shadow project to an existing\naccount is a v2 feature.", "operationId": "claim_v1_agent_signup_claim_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Claim", "tags": [ "Agent Signup" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent-signup/claim/verify": { "post": { "description": "Complete the claim: the shadow account becomes a normal free-tier\naccount. Same API key, same collection, all memories intact; lifetime\ncaps and expiry stop applying immediately.", "operationId": "claim_verify_v1_agent_signup_claim_verify_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Claim Verify", "tags": [ "Agent Signup" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent-signup/whoami": { "get": { "description": "Tier, usage, and expiry for the calling key. Works for shadow and\nnormal accounts \u2014 agents poll this to know when to suggest claiming.", "operationId": "whoami_v1_agent_signup_whoami_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whoami", "tags": [ "Agent Signup" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent/tools": { "get": { "description": "Discover all available actions that can be executed through the agent API.\n\n Returns detailed information about each tool including:\n - Name and description\n - Category\n - Required parameters (JSON Schema)\n - Examples", "operationId": "list_agent_tools_v1_agent_tools_get", "parameters": [ { "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Available Actions", "tags": [ "Agent" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/agent/tools/{action_name}": { "get": { "description": "Get detailed information about a specific action.", "operationId": "get_tool_info_v1_agent_tools__action_name__get", "parameters": [ { "in": "path", "name": "action_name", "required": true, "schema": { "title": "Action Name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolInfo" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Action Details", "tags": [ "Agent" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/anomalies/detect": { "get": { "description": "Detect behavioral anomalies for the current user with cursor-based pagination.\n\nReturns anomalies in:\n- Access patterns (spikes/drops)\n- Topic shifts (interest changes)\n- Temporal patterns (schedule changes)\n- Importance drift (preference changes)\n\nArgs:\n time_window_days: Number of days to analyze (default: 30)\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "detect_anomalies_v1_anomalies_detect_get", "parameters": [ { "in": "query", "name": "time_window_days", "required": false, "schema": { "default": 30, "title": "Time Window Days", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_AnomalyResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detect Anomalies", "tags": [ "Anomaly Detection" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/auth/account": { "delete": { "description": "Delete the current user's account.\n\nSOC 2 Controls:\n- CC6.1: Account deletion with proper authorization\n- CC7.1: Security event logging for account deletion\n- CC7.2: GDPR Article 17 - Right to erasure\n\nThis endpoint performs a soft delete by default to comply with\ndata retention requirements while respecting user privacy.\nAssociated data (memories, collections, API keys) will be marked\nfor deletion and removed after the retention period.", "operationId": "delete_account_v1_auth_account_delete", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeleteResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Account", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/api-keys": { "get": { "description": "List all API keys for the current user.\n\nNote: The full key is never returned after creation for security.\nOnly the prefix is shown to help identify keys.", "operationId": "list_api_keys_v1_auth_api_keys_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/APIKeyListItem" }, "title": "Response List Api Keys V1 Auth Api Keys Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Api Keys", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Create a new API key.\n\nThe full API key is only returned once. Store it securely.", "operationId": "create_api_key_v1_auth_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Api Key", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/api-keys/{key_id}": { "delete": { "description": "Delete an API key.\n\nThis action cannot be undone. The key will immediately stop working.", "operationId": "delete_api_key_v1_auth_api_keys__key_id__delete", "parameters": [ { "in": "path", "name": "key_id", "required": true, "schema": { "title": "Key Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Api Key", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/change-password": { "post": { "description": "Change password for authenticated user.\n\nRequires the current password for verification before setting new password.\nOAuth-only users cannot use this endpoint (they have no password).", "operationId": "change_password_v1_auth_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change Password", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/forgot-password": { "post": { "description": "Request a password reset/set via OTP.\n\nSends a 6-digit OTP code to the user's email if the account exists.\nWorks for both local and OAuth users:\n- Local users: Reset their existing password\n- OAuth users: Set a new password (allows login via email/password in addition to OAuth)\n\nAlways returns success message to prevent email enumeration.", "operationId": "forgot_password_v1_auth_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Forgot Password", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/google/callback": { "post": { "description": "Handle Google OAuth callback.\n\nSOC 2 Controls:\n- CC6.3: CSRF protection with state validation\n- CC7.1: Security event logging\n\nExchanges the authorization code for tokens and creates/logs in the user.", "operationId": "google_callback_v1_auth_google_callback_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAuthRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GoogleAuthResponse" }, { "$ref": "#/components/schemas/MFARequiredResponse" } ], "title": "Response Google Callback V1 Auth Google Callback Post" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Google Callback", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/google/login": { "get": { "description": "Get Google OAuth login URL with CSRF protection.\n\nSOC 2 Control: CC6.3 (CSRF protection with state parameter)\n\nReturns the URL to redirect the user to Google's OAuth consent screen.\nThe state parameter is cryptographically random and will be validated\non callback to prevent CSRF attacks.", "operationId": "google_login_v1_auth_google_login_get", "parameters": [ { "in": "query", "name": "redirect_uri", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Uri" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Google Login", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/login": { "post": { "description": "Login with email and password.\n\nReturns an access token for authenticated requests.\n\nSOC 2 Controls:\n- CC6.1: Authentication with brute force protection\n- CC7.1: Security event logging", "operationId": "login_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLogin" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "$ref": "#/components/schemas/MFARequiredResponse" } ], "title": "Response Login V1 Auth Login Post" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Login", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/logout": { "post": { "description": "Logout and revoke the current access token.\n\nSOC 2 Controls:\n- CC6.1: Session revocation\n- CC7.1: Security event logging\n\nThe token will be added to the revocation list and will no longer\nbe valid for authentication, even before its natural expiry.", "operationId": "logout_v1_auth_logout_post", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Logout", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/logout-all": { "post": { "description": "Logout from all sessions by revoking all tokens.\n\nSOC 2 Controls:\n- CC6.1: Session management\n- CC7.1: Security event logging\n\nThis will invalidate all active sessions for the user.", "operationId": "logout_all_v1_auth_logout_all_post", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Logout All", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/me": { "get": { "description": "Get current user information.", "operationId": "get_current_user_info_v1_auth_me_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Current User Info", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/register": { "post": { "description": "Register a new user.\n\nCreates a new user account and returns one complete access/refresh session.\n\nSOC 2 Controls:\n- CC6.1: Strong password validation\n- CC7.1: Security event logging", "operationId": "register_v1_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRegister" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Register", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/reset-password": { "post": { "description": "Reset password using the verified reset token.\n\nUses the token obtained from /verify-reset-otp endpoint.", "operationId": "reset_password_v1_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Reset Password", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/token": { "post": { "description": "OAuth2 compatible token endpoint.\n\nUses username field for email and returns access token.", "operationId": "login_oauth_v1_auth_token_post", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_login_oauth_v1_auth_token_post" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "$ref": "#/components/schemas/MFARequiredResponse" } ], "title": "Response Login Oauth V1 Auth Token Post" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Login Oauth", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/token/refresh": { "post": { "description": "Refresh an access token using a valid refresh token.\n\nThis endpoint allows clients to obtain a new access token without requiring\nthe user to re-authenticate, improving user experience while maintaining security.\n\nSOC 2 Controls:\n- CC6.1: Token lifecycle management with refresh token validation\n- CC7.1: Security event logging for token refresh", "operationId": "refresh_access_token_v1_auth_token_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Refresh Access Token", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/auth/verify-reset-otp": { "post": { "description": "Verify the password reset OTP code.\n\nReturns a short-lived reset token if OTP is valid.", "operationId": "verify_reset_otp_v1_auth_verify_reset_otp_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResetOTPRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResetOTPResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Verify Reset Otp", "tags": [ "Authentication" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/checkout": { "post": { "description": "Create a Stripe checkout session for subscription.\n\nReturns a checkout URL to redirect the user to Stripe's hosted checkout page.\nAfter successful payment, user is redirected to success_url with session_id.", "operationId": "create_checkout_v1_billing_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Checkout", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/checkout/complete": { "post": { "description": "Complete a checkout and create the subscription.\n\nCall this after successful payment to finalize subscription creation.", "operationId": "complete_checkout_v1_billing_checkout_complete_post", "parameters": [ { "description": "Stripe checkout session ID", "in": "query", "name": "session_id", "required": true, "schema": { "description": "Stripe checkout session ID", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Complete Checkout", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/downgrade": { "post": { "description": "Downgrade the caller's subscription to the specified plan tier or name.", "operationId": "downgrade_plan_v1_billing_downgrade_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanSwitchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Downgrade Plan", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/enterprise/sync-usage": { "post": { "description": "Push this period's actual AI usage as a Stripe invoice item. Normally triggered automatically by the invoice.upcoming webhook. Enterprise users and admins can call this manually as a safety valve.", "operationId": "sync_enterprise_usage_v1_billing_enterprise_sync_usage_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sync Enterprise Usage to Stripe", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/invoices": { "get": { "description": "List user's invoices.", "operationId": "list_invoices_v1_billing_invoices_get", "parameters": [ { "description": "Max invoices to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max invoices to return", "maximum": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/InvoiceResponse" }, "title": "Response List Invoices V1 Billing Invoices Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Invoices", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/overage": { "get": { "description": "Return the current user's overage configuration.", "operationId": "get_overage_settings_v1_billing_overage_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSettingsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Overage Settings", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Enable/disable overage + set spending cap.\n\nRestrictions:\n - FREE users can't enable overage (no Stripe subscription to charge)\n - ENTERPRISE users don't use the overage system (post-paid metered instead)\n - Effective immediately; no Stripe round-trip needed", "operationId": "update_overage_settings_v1_billing_overage_patch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSettingsResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Overage Settings", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/payment-methods": { "get": { "description": "List user's payment methods.", "operationId": "list_payment_methods_v1_billing_payment_methods_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "title": "Response List Payment Methods V1 Billing Payment Methods Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Payment Methods", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/plans": { "get": { "description": "List all available subscription plans.\n\nReturns active plans sorted by display order.\nNo authentication required - this is a public endpoint.", "operationId": "list_plans_v1_billing_plans_get", "parameters": [ { "description": "Filter by billing interval (monthly/yearly)", "in": "query", "name": "billing_interval", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/BillingInterval" }, { "type": "null" } ], "description": "Filter by billing interval (monthly/yearly)", "title": "Billing Interval" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PlanResponse" }, "title": "Response List Plans V1 Billing Plans Get", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "List Plans", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/plans/{plan_id}": { "get": { "description": "Get details for a specific plan.", "operationId": "get_plan_v1_billing_plans__plan_id__get", "parameters": [ { "in": "path", "name": "plan_id", "required": true, "schema": { "title": "Plan Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Plan", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/portal": { "post": { "description": "Create a Stripe Billing Portal session.\n\nRedirects user to Stripe's hosted billing portal where they can:\n- View and download invoices\n- Update payment methods\n- Cancel subscription\n- View billing history", "operationId": "create_billing_portal_v1_billing_portal_post", "parameters": [ { "description": "URL to return to after portal session", "in": "query", "name": "return_url", "required": true, "schema": { "description": "URL to return to after portal session", "title": "Return Url", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Billing Portal", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/subscription": { "get": { "description": "Get current user's subscription and tier info.\n\nAlways returns the user's current tier, even without a Stripe subscription.\nUsers on free tier or with manually-assigned tiers will see their tier\nwithout Stripe subscription details.", "operationId": "get_subscription_v1_billing_subscription_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Subscription", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/subscription/cancel": { "post": { "description": "Cancel subscription.\n\nBy default, cancels at period end (user keeps access until then).\nSet cancel_immediately=true to cancel immediately.", "operationId": "cancel_subscription_v1_billing_subscription_cancel_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Subscription", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/subscription/change-plan": { "post": { "description": "Change subscription plan (upgrade or downgrade).\n\nBy default, charges are prorated.", "operationId": "change_plan_v1_billing_subscription_change_plan_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change Plan", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/subscription/resume": { "post": { "description": "Resume a canceled subscription.\n\nOnly works if subscription was set to cancel at period end.", "operationId": "resume_subscription_v1_billing_subscription_resume_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume Subscription", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/topup": { "post": { "description": "Create a Stripe checkout session to purchase additional managed AI credits", "operationId": "create_credit_topup_v1_billing_topup_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditTopupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Credit Top-Up Checkout", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/topup/history": { "get": { "description": "List credit top-up purchases", "operationId": "get_topup_history_v1_billing_topup_history_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credit Purchase History", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/upgrade": { "post": { "description": "Upgrade the caller's subscription to the specified plan tier or name.", "operationId": "upgrade_plan_v1_billing_upgrade_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanSwitchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upgrade Plan", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/billing/usage": { "get": { "description": "Get current billing period usage.\n\nShows memory count, API calls, and token usage against limits.", "operationId": "get_usage_v1_billing_usage_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Usage", "tags": [ "Billing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/byok/providers": { "get": { "description": "List stored BYOK provider keys (preview only \u2014 actual key never returned).", "operationId": "list_byok_keys_v1_byok_providers_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/KeyResponse" }, "title": "Response List Byok Keys V1 Byok Providers Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Byok Keys", "tags": [ "BYOK", "BYOK" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/byok/providers/{provider}": { "delete": { "description": "Remove a BYOK API key for a provider.", "operationId": "delete_byok_key_v1_byok_providers__provider__delete", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Byok Key", "tags": [ "BYOK", "BYOK" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "post": { "description": "Add or replace a BYOK API key for a provider.\nThe key is encrypted before storage and a background validation is triggered.", "operationId": "add_byok_key_v1_byok_providers__provider__post", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKeyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKeyResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Byok Key", "tags": [ "BYOK", "BYOK" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/byok/providers/{provider}/validate": { "post": { "description": "Trigger synchronous validation of the stored key for a provider.", "operationId": "validate_byok_key_v1_byok_providers__provider__validate_post", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Validate Byok Key V1 Byok Providers Provider Validate Post", "type": "object" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Validate Byok Key", "tags": [ "BYOK", "BYOK" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/chat/ask": { "post": { "description": "Universal AI assistant endpoint for both landing page and dashboard.\n\n## Landing Page Chatbot (unauthenticated):\n- ONLY answers Hebbrix API documentation questions\n- Refuses general knowledge questions\n- No access to user data\n\n## Dashboard Chatbot (authenticated):\n- Answers user's dashboard details (how many memories, documents, etc.)\n- Searches through user's stored memories\n- Provides API documentation help when asked\n- Refuses general knowledge unrelated to Hebbrix or user's data", "operationId": "ask_question_v1_chat_ask_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask Question", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1-50 by served model", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "chat_nano", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/chat/ask/stream": { "post": { "description": "Streaming version of the /ask endpoint.\nReturns Server-Sent Events (SSE) for real-time response streaming.", "operationId": "ask_question_stream_v1_chat_ask_stream_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask Question Stream", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1-50 by served model", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "chat_nano", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/chat/completions": { "post": { "description": "Create a chat completion with automatic memory integration.\n\nThis is the flagship endpoint that makes Hebbrix incredibly easy to use:\n- Automatically retrieves relevant memories\n- Injects user profile for personalization\n- Manages conversation sessions\n- Logs interactions for RL training\n- Returns OpenAI-compatible responses\n\n## Example Usage:\n\n```python\nfrom hebbrix import MemoryChat\n\nchat = MemoryChat(api_key=\"mem_sk_...\")\nresponse = chat.send(\"What's my favorite food?\", session_id=\"user_123\")\n```\n\nThat's it! Just 3 lines of code for full memory-powered conversations.", "operationId": "create_chat_completion_v1_chat_completions_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Chat Completion", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1-50 by served model", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "chat_nano", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/chat/sessions": { "get": { "description": "List user's chat sessions.", "operationId": "list_sessions_v1_chat_sessions_get", "parameters": [ { "in": "query", "name": "active_only", "required": false, "schema": { "default": true, "title": "Active Only", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Sessions", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/chat/sessions/{session_id}": { "delete": { "description": "Delete a chat session.", "operationId": "delete_session_v1_chat_sessions__session_id__delete", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Session", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get session information and statistics.", "operationId": "get_session_info_v1_chat_sessions__session_id__get", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Session Info", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/chat/web-search": { "post": { "description": "Perform real-time web search with OpenAI's web search tool.\n\nThis endpoint provides:\n- Real-time internet search\n- Inline citations with URLs\n- Source tracking\n- Domain filtering (optional)\n- Location-based results (optional)\n\n## Usage:\n```json\n{\n \"query\": \"What are the latest AI news today?\",\n \"search_context_size\": \"medium\"\n}\n```\n\n## With domain filtering:\n```json\n{\n \"query\": \"Latest research on transformers\",\n \"allowed_domains\": [\"arxiv.org\", \"openai.com\", \"anthropic.com\"]\n}\n```", "operationId": "web_search_v1_chat_web_search_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Web Search", "tags": [ "Chat Completions" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1-50 by served model", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "chat_nano", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/coding-agent/check-error": { "post": { "description": "Check if an error has been encountered before.\n\nReturns:\n- Whether error was seen before\n- How many times it occurred\n- Similar past errors\n- Last successful fix (if any)\n\nUse this BEFORE attempting to fix an error to avoid repeated mistakes.", "operationId": "check_error_v1_coding_agent_check_error_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckErrorRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Error", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/coding-history": { "post": { "description": "Get coding history for analysis.\n\nReturns chronological list of:\n- Code changes\n- Errors encountered\n- Fixes applied\n- Success/failure rates\n\nUse this to review what the agent has done.", "operationId": "get_coding_history_v1_coding_agent_coding_history_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodingHistoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Coding History", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/get-fix-suggestions": { "post": { "description": "Get fix suggestions based on past successful resolutions.\n\nReturns ranked list of suggested fixes with:\n- Fix strategy\n- Description\n- Confidence score\n- Code examples (if available)\n\nUse this to leverage past learnings when fixing errors.", "operationId": "get_fix_suggestions_v1_coding_agent_get_fix_suggestions_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFixSuggestionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Fix Suggestions", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/health": { "get": { "description": "Health check for coding agent endpoints.", "operationId": "coding_agent_health_v1_coding_agent_health_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Coding Agent Health", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/track-code-change": { "post": { "description": "Track a code change made by the agent.\n\nThis creates a memory of the code change and enables:\n- Tracking what the agent modified\n- Learning from successful changes\n- Reviewing change history", "operationId": "track_code_change_v1_coding_agent_track_code_change_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackCodeChangeRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Track Code Change", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/track-error": { "post": { "description": "Track an error encountered by the agent.\n\nThis creates a memory of the error and:\n- Identifies if it's a repeated mistake\n- Suggests fixes based on past resolutions\n- Updates error pattern statistics\n- Returns warnings if seen multiple times\n\n**Always call this when encountering an error!**", "operationId": "track_error_v1_coding_agent_track_error_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackErrorRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Track Error", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/coding-agent/track-fix": { "post": { "description": "Track a fix applied by the agent.\n\nThis records:\n- What fix was applied\n- Whether it was successful\n- Code before/after\n- Time to fix\n\nUse this to build knowledge of what fixes work!\n**Always call this after applying a fix!**", "operationId": "track_fix_v1_coding_agent_track_fix_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackFixRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Track Fix", "tags": [ "Coding Agents" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/collections": { "get": { "description": "List collections with cursor-based pagination.\n\nReturns next_cursor for pagination - pass it to the next request to get more results.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\nArgs:\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)\n name: Exact-match filter on collection name (case-sensitive).\n Use this to look up a customer's collection by stable name\n without paginating through the whole workspace.\n name_prefix: Prefix-match filter on collection name (case-insensitive).\n Useful for tenant-style \"{prefix}-{id}\" naming schemes.", "operationId": "list_collections_v1_collections_get", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "name", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, { "in": "query", "name": "name_prefix", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name Prefix" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_CollectionResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Collections", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Create a new memory collection.\n\nCollections allow you to organize memories into logical groups.\n\nIdempotent on name: if a collection with the same name already exists in the\nsame scope, the existing collection is returned (HTTP 200, ``created: false``)\ninstead of creating a duplicate. This keeps the name -> id mapping unique so\n``GET /collections?name=`` resolves to a single collection.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n- Defaults to 'api' for backwards compatibility", "operationId": "create_collection_v1_collections_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/all": { "delete": { "description": "Delete collections (and their memories) for the current user.\n\n**WARNING: irreversible.** Use `dry_run=true` to preview the blast radius,\nand optionally send `X-Hebbrix-Confirm-Destructive: all-collections` to gate\nthe call. Deletes collections + their memories across Postgres, Qdrant,\nNeo4j, and BM25.\n\n#10 lifecycle cleanup: narrow the blast radius with `only_empty=true`\n(drop only zero-memory collections) and/or `name_contains=test` (drop only\nmatching names) \u2014 both STRICTLY reduce what is deleted vs the default\ndelete-everything behavior.", "operationId": "delete_all_collections_v1_collections_all_delete", "parameters": [ { "description": "Preview how many collections WOULD be deleted without deleting anything.", "in": "query", "name": "dry_run", "required": false, "schema": { "default": false, "description": "Preview how many collections WOULD be deleted without deleting anything.", "title": "Dry Run", "type": "boolean" } }, { "description": "#10 lifecycle cleanup: when true, delete ONLY collections that currently hold zero memories. Safest way to clear accumulated empty test collections without touching collections that hold real data.", "in": "query", "name": "only_empty", "required": false, "schema": { "default": false, "description": "#10 lifecycle cleanup: when true, delete ONLY collections that currently hold zero memories. Safest way to clear accumulated empty test collections without touching collections that hold real data.", "title": "Only Empty", "type": "boolean" } }, { "description": "#10 lifecycle cleanup: when set, delete ONLY collections whose name contains this substring (case-insensitive) \u2014 e.g. 'test' to clear test scaffolding. Combine with only_empty to be extra safe.", "in": "query", "name": "name_contains", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "#10 lifecycle cleanup: when set, delete ONLY collections whose name contains this substring (case-insensitive) \u2014 e.g. 'test' to clear test scaffolding. Combine with only_empty to be extra safe.", "title": "Name Contains" } }, { "description": "Optional safety confirmation. If provided it must equal 'all-collections'; otherwise the request is rejected. Omitting it preserves existing behavior.", "in": "header", "name": "X-Hebbrix-Confirm-Destructive", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional safety confirmation. If provided it must equal 'all-collections'; otherwise the request is rejected. Omitting it preserves existing behavior.", "title": "X-Hebbrix-Confirm-Destructive" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__collections__BulkDeleteResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete All Collections", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/bulk-delete": { "post": { "description": "Delete specific collections by ID (bulk operation).\nOnly deletes collections owned by the current user.", "operationId": "bulk_delete_collections_v1_collections_bulk_delete_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__collections__BulkDeleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__collections__BulkDeleteResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Delete Collections", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/default": { "get": { "description": "Get or create the default collection for this user/app.\n\nThis endpoint is **idempotent** - calling it multiple times returns the same collection.\nUse this for integrations that need a reliable collection that auto-recovers if deleted.\n\n**Data Isolation:**\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\n**Use Cases:**\n- Chatbots, AI agents\n- CRM/ERP integrations\n- Workflow automations (Zapier, n8n)\n- Any app that needs persistent memory without manual collection management\n\n**Isolation Levels:**\n- No parameters: Returns user's default collection (`__default__`)\n- With app_id: Returns app-specific collection (`__app__{app_id}__default__`)\n- With app_id + namespace: Returns namespaced collection (`__app__{app_id}__{namespace}__`)\n\n**Examples:**\n```\nGET /collections/default\n\u2192 Returns: __default__ collection\n\nGET /collections/default?app_id=my-chatbot\n\u2192 Returns: __app__my-chatbot__default__ collection\n\nGET /collections/default?app_id=my-crm&namespace=customer-support\n\u2192 Returns: __app__my-crm__customer-support__ collection\n```", "operationId": "get_default_collection_v1_collections_default_get", "parameters": [ { "description": "Application identifier for app-specific isolation (like Mem0's agent_id)", "in": "query", "name": "app_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Application identifier for app-specific isolation (like Mem0's agent_id)", "title": "App Id" } }, { "description": "Namespace within the app for further isolation", "in": "query", "name": "namespace", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Namespace within the app for further isolation", "title": "Namespace" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Default Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/ensure": { "post": { "description": "Verify and restore a specific collection.\n\nThis endpoint verifies that a collection exists and is owned by you.\nIf the collection was soft-deleted, it restores it.\n\n**Data Isolation:**\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\n**Security:**\n- Only returns collections you own AND matching the source\n- Cannot create collections with arbitrary IDs (use POST /collections instead)\n- Automatically restores soft-deleted collections you own\n\n**Use Cases:**\n- Pre-validating collection_id before batch operations\n- Recovering from accidental collection soft-deletion\n- Verifying collection ownership before use\n\n**Behavior:**\n- Collection exists and owned: Returns it\n- Collection soft-deleted and owned: Restores and returns it\n- Collection not found: Returns 404\n- Collection owned by another user: Returns 404 (security: no information leak)\n\n**Example:**\n```json\nPOST /collections/ensure\n{\n \"collection_id\": \"abc-123-def\",\n \"fallback_name\": \"My Integration\"\n}\n```", "operationId": "ensure_collection_v1_collections_ensure_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEnsureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/{collection_id}": { "delete": { "description": "Delete a collection.\n\nThis will cascade delete all memories in the collection.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "delete_collection_v1_collections__collection_id__delete", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get a specific collection by ID.\n\nReturns ETag header for concurrency control.\nUse this ETag in If-Match header when updating to prevent conflicts.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "get_collection_v1_collections__collection_id__get", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Update a collection.\n\nSupports optimistic locking via If-Match header.\nInclude the ETag from GET response to prevent concurrent modifications.\nReturns 412 Precondition Failed if resource has been modified.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "update_collection_v1_collections__collection_id__patch", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "if-match", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "If-Match" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Collection", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/{collection_id}/kg/rebuild": { "post": { "description": "Rebuild this collection's knowledge graph from its source memories.\n\nRe-extracts every source memory through the current graph pipeline. Graph V2\nkeeps the last known-good projection queryable until every durable child\nsucceeds, then reconciles stale facts and memberships. The legacy path keeps\nits purge-and-replay behavior. Asynchronous: returns 202 immediately; search,\nmemories, and profile data are unaffected.", "operationId": "rebuild_collection_knowledge_graph_v1_collections__collection_id__kg_rebuild_post", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rebuild Collection Knowledge Graph", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/{collection_id}/readiness": { "get": { "description": "Indexing readiness for the collection.\n\nReturns counts of memories by `processing_status`. A client integrating\nHebbrix can poll this endpoint after a batch ingest to confirm that\nall memories are indexed and searchable before issuing search queries.\n\nResponse:\n {\n \"collection_id\": \"...\",\n \"ready\": true, # pending == 0 AND processing == 0\n \"completed\": 50,\n \"pending\": 0,\n \"processing\": 0,\n \"failed\": 0,\n \"total\": 50\n }\n\nAuthorisation: same as `GET /{collection_id}` \u2014 must own the collection\nand source must match.", "operationId": "get_collection_readiness_v1_collections__collection_id__readiness_get", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Collection Readiness", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/{collection_id}/rl-reranking": { "post": { "description": "Opt this collection into (or out of) the per-collection RL reranker.\n\n2026-06-03: the trained Answer-Agent reranker is OFF by default. Enable it\nper collection here; it then applies to /v1/search for this collection ONLY\nonce that collection has accumulated enough usage to train a checkpoint\n(until then, retrieval transparently falls back to the heuristic ranking \u2014\na cold-start collection never gets an untrained model).\n\nSets `custom_metadata.rl_reranking_enabled` (merged, not overwritten).", "operationId": "set_collection_rl_reranking_v1_collections__collection_id__rl_reranking_post", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLRerankingToggle" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Collection Rl Reranking", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/collections/{collection_id}/rl-reranking/train": { "post": { "description": "Manually trigger a training pass for this collection's RL reranker.\n\n2026-06-03: training also runs automatically on a 6-hour schedule for every\nopted-in collection, so this is optional \u2014 use it to retrain immediately after\na burst of usage. The job trains only from THIS collection's reward data and\nsaves a checkpoint ONLY if it beats the heuristic on a held-out split; if the\ncollection lacks enough data it is a safe no-op (serving stays on heuristic).\nRequires the collection to be opted in first (POST .../rl-reranking).", "operationId": "trigger_collection_rl_training_v1_collections__collection_id__rl_reranking_train_post", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Collection Rl Training", "tags": [ "Collections" ], "x-hebbrix-data-scope": { "authorization": "ownership verified before data access", "classification": "collection_scoped" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/confidence": { "get": { "description": "Return a confidence score for the given query.\n\nThe agent should call this before taking an autonomous action so it can\ndecide whether it has enough grounding to proceed without asking the user.\n\nConfidence logic\n----------------\n1. **memory_signal** \u2014 derived from how many relevant memories exist and\n how highly scored the best one is.\n2. **correction_boost** \u2014 added when the user has recent corrections\n (corrections are knowledge \u2014 the system was taught the right answer).\n3. **confidence = clamp(memory_signal + correction_boost, 0, 1)**\n\nRecommendations\n---------------\n- ``>=0.7`` \u2192 ``act_autonomously``\n- ``>=0.4`` \u2192 ``proceed_with_caution``\n- ``<0.4`` \u2192 ``ask_user``", "operationId": "get_confidence_v1_confidence_get", "parameters": [ { "description": "The action / question to evaluate", "in": "query", "name": "query", "required": true, "schema": { "description": "The action / question to evaluate", "minLength": 1, "title": "Query", "type": "string" } }, { "description": "Restrict search to a collection", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict search to a collection", "title": "Collection Id" } }, { "description": "End-user scope (alias: enduser_id)", "in": "query", "name": "end_user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user scope (alias: enduser_id)", "title": "End User Id" } }, { "in": "query", "name": "enduser_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enduser Id" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfidenceResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check action confidence", "tags": [ "Confidence Scoring" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/consent": { "get": { "description": "Get current consent status for all consent types.\n\nReturns the latest consent decision for each type.", "operationId": "get_all_consents_v1_consent_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllConsentsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get All Consents", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "post": { "description": "Record user consent for a specific purpose.\n\nCreates an immutable audit trail entry for the consent decision.\nConsent can be granted or withdrawn.\n\nGDPR Article 7: Conditions for consent\nSOC 2 Control: CC2.1 (Privacy commitments)", "operationId": "record_consent_v1_consent_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRecordedResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Consent", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consent/check/{consent_type}": { "get": { "description": "Quick check if user has active consent for a specific type.\n\nReturns true/false for simple consent gates.", "operationId": "check_consent_v1_consent_check__consent_type__get", "parameters": [ { "in": "path", "name": "consent_type", "required": true, "schema": { "$ref": "#/components/schemas/ConsentTypeEnum" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "title": "Response Check Consent V1 Consent Check Consent Type Get", "type": "boolean" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Consent", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consent/history": { "get": { "description": "Get full consent history for the user.\n\nOptionally filter by consent type.\nReturns all consent records in chronological order.\n\nGDPR Article 17: Right to erasure (audit trail)", "operationId": "get_consent_history_v1_consent_history_get", "parameters": [ { "in": "query", "name": "consent_type", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConsentTypeEnum" }, { "type": "null" } ], "title": "Consent Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentHistoryResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Consent History", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consent/{consent_type}": { "delete": { "description": "Withdraw consent for a specific purpose.\n\nCreates a new consent record with granted=False.\nThis maintains the full audit trail.\n\nGDPR Article 7(3): Right to withdraw consent", "operationId": "withdraw_consent_v1_consent__consent_type__delete", "parameters": [ { "in": "path", "name": "consent_type", "required": true, "schema": { "$ref": "#/components/schemas/ConsentTypeEnum" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentWithdrawResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Withdraw Consent", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get current consent status for a specific type.\n\nReturns whether consent is currently granted and when it was last updated.", "operationId": "get_consent_status_v1_consent__consent_type__get", "parameters": [ { "in": "path", "name": "consent_type", "required": true, "schema": { "$ref": "#/components/schemas/ConsentTypeEnum" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Consent Status", "tags": [ "Consent Management" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consolidation/consolidate": { "post": { "description": "Consolidate episodic memories to semantic.\n\nRuns consolidation pipeline: pattern extraction \u2192 semantic creation \u2192 selective retention.", "operationId": "consolidate_memories_v1_consolidation_consolidate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__routes__consolidation__ConsolidateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consolidate Memories", "tags": [ "Memory Consolidation", "Memory Consolidation" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consolidation/consolidate/{collection_id}/run-now": { "post": { "description": "Run consolidation synchronously (blocking).\n\nReturns results immediately instead of running in background.", "operationId": "consolidate_now_v1_consolidation_consolidate__collection_id__run_now_post", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "query", "name": "lookback_days", "required": false, "schema": { "default": 7, "maximum": 365, "minimum": 1, "title": "Lookback Days", "type": "integer" } }, { "in": "query", "name": "utility_threshold", "required": false, "schema": { "default": 0.3, "maximum": 1.0, "minimum": 0.0, "title": "Utility Threshold", "type": "number" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consolidate Now", "tags": [ "Memory Consolidation", "Memory Consolidation" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consolidation/schedule/{collection_id}": { "post": { "description": "Periodic consolidation is not exposed until schedules are durably stored.", "operationId": "schedule_consolidation_v1_consolidation_schedule__collection_id__post", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "query", "name": "interval_hours", "required": false, "schema": { "default": 24, "maximum": 168, "minimum": 1, "title": "Interval Hours", "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule Consolidation", "tags": [ "Memory Consolidation", "Memory Consolidation" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/consolidation/stats/{collection_id}": { "get": { "description": "Get consolidation statistics for collection.\n\nReturns memory counts, retention rates, etc.", "operationId": "get_consolidation_stats_v1_consolidation_stats__collection_id__get", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Consolidation Stats", "tags": [ "Memory Consolidation", "Memory Consolidation" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/contact/enterprise": { "post": { "description": "Submit an enterprise sales inquiry. Sends notification to the Hebbrix sales team.", "operationId": "submit_enterprise_inquiry_v1_contact_enterprise_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseContactRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseContactResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Enterprise Sales Inquiry", "tags": [ "Contact" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/conversation": { "get": { "description": "Generate personalized conversation starters based on user profile.\n\n Features:\n - LLM-powered intelligent question generation\n - Context-aware based on user interests, projects, and expertise\n - Fallback to template-based starters if LLM unavailable\n - Generic starters for new users without profiles\n\n Use cases:\n - Kickstart user conversations in chatbots\n - Provide suggested topics in UI\n - Guide users toward productive interactions", "operationId": "get_conversation_starters_v1_conversation_get", "parameters": [ { "description": "Number of starters to generate", "in": "query", "name": "count", "required": false, "schema": { "default": 5, "description": "Number of starters to generate", "maximum": 10, "minimum": 1, "title": "Count", "type": "integer" } }, { "description": "Whether to use LLM for generation", "in": "query", "name": "use_llm", "required": false, "schema": { "default": true, "description": "Whether to use LLM for generation", "title": "Use Llm", "type": "boolean" } }, { "description": "LLM provider (openai, anthropic, gemini)", "in": "query", "name": "provider", "required": false, "schema": { "default": "openai", "description": "LLM provider (openai, anthropic, gemini)", "title": "Provider", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartersResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Conversation Starters", "tags": [ "Conversation Starters" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/conversation/generic": { "get": { "description": "Get generic conversation starters (not personalized)", "operationId": "get_generic_starters_v1_conversation_generic_get", "parameters": [ { "in": "query", "name": "count", "required": false, "schema": { "default": 5, "maximum": 10, "minimum": 1, "title": "Count", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartersResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Generic Conversation Starters", "tags": [ "Conversation Starters" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/corrections": { "get": { "description": "List all corrections for the authenticated user.", "operationId": "list_corrections_v1_corrections_get", "parameters": [ { "description": "Filter by type: preference, factual, or procedural", "in": "query", "name": "correction_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: preference, factual, or procedural", "title": "Correction Type" } }, { "description": "Scope to a single collection. When set, only that collection's corrections are listed. Omit to list all of the account's corrections.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope to a single collection. When set, only that collection's corrections are listed. Omit to list all of the account's corrections.", "title": "Collection Id" } }, { "description": "Include soft-deleted corrections", "in": "query", "name": "include_inactive", "required": false, "schema": { "default": false, "description": "Include soft-deleted corrections", "title": "Include Inactive", "type": "boolean" } }, { "description": "Max corrections to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max corrections to return", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CorrectionResponse" }, "title": "Response List Corrections V1 Corrections Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List All Corrections", "tags": [ "Correction Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Store a new correction to an agent action or memory.\n\n Corrections are preference signals used during retrieval \u2014 agents query\n `GET /corrections/relevant` before acting so they know what the user\n wants them to avoid or prefer.", "operationId": "create_correction_v1_corrections_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Store a Correction", "tags": [ "Correction Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/corrections/relevant": { "get": { "description": "Retrieve corrections relevant to a query string.\n\n Agents should call this endpoint **before acting** so they can incorporate\n user preferences and avoid previously-corrected mistakes.\n\n Currently returns the most recent active corrections for the user filtered\n by type (if provided). Future versions will use semantic similarity.", "operationId": "get_relevant_corrections_v1_corrections_relevant_get", "parameters": [ { "description": "The query / task the agent is about to perform", "in": "query", "name": "query", "required": true, "schema": { "description": "The query / task the agent is about to perform", "title": "Query", "type": "string" } }, { "description": "Filter by type: preference, factual, or procedural", "in": "query", "name": "correction_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: preference, factual, or procedural", "title": "Correction Type" } }, { "description": "Scope corrections to a single END-USER (multi-tenant isolation). When set, only corrections created for this end-user are returned.", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope corrections to a single END-USER (multi-tenant isolation). When set, only corrections created for this end-user are returned.", "title": "User Id" } }, { "description": "Scope corrections to a single agent (multi-agent isolation). When set, only corrections created for this agent are returned.", "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope corrections to a single agent (multi-agent isolation). When set, only corrections created for this agent are returned.", "title": "Agent Id" } }, { "description": "Scope corrections to a single collection (multi-tenant isolation). When set, only corrections created for this collection are returned \u2014 another collection's corrections will NOT leak in. Omit to return account-wide corrections (legacy/backward-compatible behavior).", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope corrections to a single collection (multi-tenant isolation). When set, only corrections created for this collection are returned \u2014 another collection's corrections will NOT leak in. Omit to return account-wide corrections (legacy/backward-compatible behavior).", "title": "Collection Id" } }, { "description": "Only meaningful with collection_id. When true, also include account-wide corrections (those created without a collection_id) alongside this collection's corrections.", "in": "query", "name": "include_global", "required": false, "schema": { "default": false, "description": "Only meaningful with collection_id. When true, also include account-wide corrections (those created without a collection_id) alongside this collection's corrections.", "title": "Include Global", "type": "boolean" } }, { "description": "Max corrections to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max corrections to return", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CorrectionResponse" }, "title": "Response Get Relevant Corrections V1 Corrections Relevant Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Relevant Corrections", "tags": [ "Correction Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/corrections/{correction_id}": { "delete": { "description": "Soft-delete a correction by setting is_active='false'.", "operationId": "delete_correction_v1_corrections__correction_id__delete", "parameters": [ { "in": "path", "name": "correction_id", "required": true, "schema": { "title": "Correction Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a Correction", "tags": [ "Correction Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Return a correction and its canonical search-delivery state.", "operationId": "get_correction_v1_corrections__correction_id__get", "parameters": [ { "in": "path", "name": "correction_id", "required": true, "schema": { "title": "Correction Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Correction Status", "tags": [ "Correction Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/decisions": { "get": { "description": "List the authenticated account's decisions, newest first.", "operationId": "list_decisions_v1_decisions_get", "parameters": [ { "description": "End-user scope (multi-tenant)", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user scope (multi-tenant)", "title": "User Id" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "decision_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decision Type" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DecisionResponse" }, "title": "Response List Decisions V1 Decisions Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List decisions", "tags": [ "Decision Outcomes" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Record a decision an agent made and what happened.", "operationId": "create_decision_v1_decisions_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Log a Decision Outcome", "tags": [ "Decision Outcomes" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/decisions/similar": { "get": { "description": "Retrieve past decisions filtered by type and/or outcome.\n\n Agents call this before making a decision to see how similar decisions\n turned out in the past \u2014 a lightweight form of case-based reasoning.\n\n Filter by `decision_type` to find decisions of the same category, and\n optionally by `outcome` to focus on successes or failures.", "operationId": "get_similar_decisions_v1_decisions_similar_get", "parameters": [ { "description": "Filter by decision type (e.g. tool_selection, deployment)", "in": "query", "name": "decision_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by decision type (e.g. tool_selection, deployment)", "title": "Decision Type" } }, { "description": "Filter by outcome: success, failure, partial, or unknown", "in": "query", "name": "outcome", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by outcome: success, failure, partial, or unknown", "title": "Outcome" } }, { "description": "Free-text description of the current situation. When provided, results are ranked by SEMANTIC RELEVANCE to this query (not recency). Accepts `description`, `q`, and `situation` as aliases.", "in": "query", "name": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description of the current situation. When provided, results are ranked by SEMANTIC RELEVANCE to this query (not recency). Accepts `description`, `q`, and `situation` as aliases.", "title": "Query" } }, { "description": "Alias of `query` (the natural field name used by /decisions POST).", "in": "query", "name": "description", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias of `query` (the natural field name used by /decisions POST).", "title": "Description" } }, { "description": "Alias of `query`.", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias of `query`.", "title": "Q" } }, { "description": "Alias of `query`.", "in": "query", "name": "situation", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias of `query`.", "title": "Situation" } }, { "description": "Scope decisions to a single END-USER (multi-tenant isolation).", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope decisions to a single END-USER (multi-tenant isolation).", "title": "User Id" } }, { "description": "Scope decisions to a single collection (multi-tenant isolation). When set, only this collection's decisions are returned \u2014 another collection's decisions will NOT leak in. Omit for account-wide (legacy/backward-compatible) behavior.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope decisions to a single collection (multi-tenant isolation). When set, only this collection's decisions are returned \u2014 another collection's decisions will NOT leak in. Omit for account-wide (legacy/backward-compatible) behavior.", "title": "Collection Id" } }, { "description": "Only meaningful with collection_id. When true, also include account-wide decisions (those logged without a collection_id).", "in": "query", "name": "include_global", "required": false, "schema": { "default": false, "description": "Only meaningful with collection_id. When true, also include account-wide decisions (those logged without a collection_id).", "title": "Include Global", "type": "boolean" } }, { "description": "Max decisions to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max decisions to return", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Customer-eval D #1: with a `query`, drop results whose semantic similarity is below this threshold (0-1). Ignored without a query.", "in": "query", "name": "min_similarity", "required": false, "schema": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Customer-eval D #1: with a `query`, drop results whose semantic similarity is below this threshold (0-1). Ignored without a query.", "title": "Min Similarity" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DecisionResponse" }, "title": "Response Get Similar Decisions V1 Decisions Similar Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Find Similar Past Decisions", "tags": [ "Decision Outcomes" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/decisions/{decision_id}": { "get": { "description": "Fetch a single decision by id (scoped to the authenticated account).", "operationId": "get_decision_v1_decisions__decision_id__get", "parameters": [ { "in": "path", "name": "decision_id", "required": true, "schema": { "title": "Decision Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a decision", "tags": [ "Decision Outcomes" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents": { "get": { "description": "List user's documents with filtering and pagination.", "operationId": "list_documents_v1_documents_get", "parameters": [ { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/DocumentStatus" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "file_type", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/DocumentType" }, { "type": "null" } ], "title": "File Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Documents", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/stats/summary": { "get": { "description": "Get document statistics for current user.", "operationId": "get_document_stats_v1_documents_stats_summary_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Document Stats", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/supported/formats": { "get": { "description": "Get list of supported document formats.", "operationId": "get_supported_formats_v1_documents_supported_formats_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Supported Formats", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/upload": { "post": { "description": "Upload a document for processing.\n\nSupported formats:\n- PDF (.pdf)\n- Microsoft Word (.docx, .doc)\n- Microsoft PowerPoint (.pptx, .ppt)\n- Microsoft Excel (.xlsx, .xls)\n- CSV/TSV (.csv, .tsv)\n- Markdown (.md, .markdown)\n- HTML (.html, .htm)\n- Plain Text (.txt)\n- Images (.jpg, .png, etc.) - with OCR\n- RTF (.rtf)\n\nCollection routing:\n- If ``collection_id`` is supplied, the document lands in that collection\n (404 if it doesn't exist or isn't owned by the caller).\n- If ``collection_id`` is omitted, the document is auto-assigned to the\n caller's default collection. The response sets\n ``collection_auto_assigned=true`` so the caller can see this happened.\n- Callers who want to refuse auto-assignment can send\n ``X-Hebbrix-Require-Collection: true`` \u2014 the request will then\n return HTTP 422 when ``collection_id`` is missing.", "operationId": "upload_document_v1_documents_upload_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_document_v1_documents_upload_post" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload Document", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/upload/batch": { "post": { "description": "Upload multiple documents at once.", "operationId": "upload_documents_batch_v1_documents_upload_batch_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_documents_batch_v1_documents_upload_batch_post" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload Documents Batch", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/{document_id}": { "delete": { "description": "Permanently delete document and associated data.", "operationId": "delete_document_v1_documents__document_id__delete", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Document", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get document details.", "operationId": "get_document_v1_documents__document_id__get", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "query", "name": "include_text", "required": false, "schema": { "default": false, "title": "Include Text", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Document", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Update document metadata.\n\nAllows updating:\n- category: Document category/classification\n- tags: List of tags for organization\n- collection_id: Move document to a different collection\n- name: Display name for the document\n- description: Optional description text", "operationId": "update_document_v1_documents__document_id__patch", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Document", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/{document_id}/chunks": { "get": { "description": "Get document chunks.", "operationId": "get_document_chunks_v1_documents__document_id__chunks_get", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Document Chunks", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/{document_id}/create-memories": { "post": { "description": "Create memory entries from processed document chunks.\n\nThis endpoint converts document chunks into memories that can be:\n- Searched semantically\n- Used in chat conversations\n- Retrieved based on context\n\nArgs:\n document_id: Document ID\n importance_threshold: Minimum importance score for chunks (0-1)\n create_summary: Create a summary memory for the entire document", "operationId": "create_memories_from_document_v1_documents__document_id__create_memories_post", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "query", "name": "importance_threshold", "required": false, "schema": { "default": 0.3, "maximum": 1.0, "minimum": 0.0, "title": "Importance Threshold", "type": "number" } }, { "in": "query", "name": "create_summary", "required": false, "schema": { "default": true, "title": "Create Summary", "type": "boolean" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Memories From Document", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/documents/{document_id}/memories": { "delete": { "description": "Delete all memories associated with a document.", "operationId": "delete_document_memories_v1_documents__document_id__memories_delete", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Document Memories", "tags": [ "Document Processing" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/fast/batch-ingest": { "post": { "description": "Accept 1-2000 memories atomically; optionally wait for searchability.", "operationId": "fast_batch_ingest_v1_fast_batch_ingest_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastBatchIngestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastBatchIngestResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Durable immediate batch ingestion", "tags": [ "Fast Ingestion" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "1 per memory", "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_batch", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/fast/memory": { "post": { "description": "Use the exact same durable batch contract for a one-memory request.", "operationId": "fast_single_memory_v1_fast_memory_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastSingleMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastSingleMemoryResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Durable immediate single-memory ingestion", "tags": [ "Fast Ingestion" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/feedback": { "post": { "description": "Convenience entry point for relevance / ranking / missing-result feedback. Set `type` or let it be inferred from the fields you send. Equivalent typed endpoints: POST /v1/feedback/relevance, /ranking, /missing.", "operationId": "submit_feedback_v1_feedback_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedFeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Feedback (unified)", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/feedback/missing": { "post": { "description": "Report when expected memory is missing from search results.\n\n This helps identify:\n - Gaps in memory retrieval\n - Issues with search query understanding\n - Memories that should have been found", "operationId": "report_missing_result_v1_feedback_missing_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissingResultRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report Missing Result", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/feedback/ranking": { "post": { "description": "Report incorrect ranking of a memory in search results.\n\n Use this when:\n - A memory appeared too high or too low in results\n - You want to correct the ranking for future searches", "operationId": "submit_ranking_feedback_v1_feedback_ranking_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingFeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Ranking Correction", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/feedback/relevance": { "post": { "description": "Provide thumbs up/down feedback on memory relevance.\n\n The system will:\n - Record the feedback for analytics\n - Adjust memory importance scores\n - Improve future retrieval for similar queries", "operationId": "submit_relevance_feedback_v1_feedback_relevance_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelevanceFeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Relevance Feedback", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/feedback/stats": { "get": { "description": "Get analytics and statistics about user feedback", "operationId": "get_feedback_stats_v1_feedback_stats_get", "parameters": [ { "description": "Number of recent feedback items", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Number of recent feedback items", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackStats" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Feedback Statistics", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/feedback/{feedback_id}": { "delete": { "description": "Delete a previously submitted feedback", "operationId": "delete_feedback_v1_feedback__feedback_id__delete", "parameters": [ { "in": "path", "name": "feedback_id", "required": true, "schema": { "title": "Feedback Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Feedback", "tags": [ "User Feedback (HITL)" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/gdpr/delete-account": { "post": { "description": "Delete user account and all associated data (GDPR Article 17).\n\nImplements soft-delete with 90-day retention period.\nData is recoverable during retention period.\n\nSOC 2 Controls:\n- CC7.1: Security audit logging for data deletion", "operationId": "delete_my_account_v1_gdpr_delete_account_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete My Account", "tags": [ "GDPR Compliance" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/gdpr/export": { "post": { "description": "Export all user data (GDPR Article 15 - Right to Access).\n\nReturns complete data export in JSON format.\n\nSOC 2 Controls:\n- CC7.1: Security audit logging for data access", "operationId": "export_my_data_v1_gdpr_export_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Export My Data V1 Gdpr Export Post", "type": "object" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export My Data", "tags": [ "GDPR Compliance" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/gdpr/restore-account": { "post": { "description": "Restore soft-deleted account within retention period.\n\nOnly works if account was deleted less than 90 days ago.", "operationId": "restore_my_account_v1_gdpr_restore_account_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AccountRestoreRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Restore My Account V1 Gdpr Restore Account Post", "type": "object" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore My Account", "tags": [ "GDPR Compliance" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/health": { "get": { "description": "Health check endpoint for load balancers and monitoring.", "operationId": "health_check_v1_health_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Health Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/health/build": { "get": { "description": "Health check endpoint for load balancers and monitoring.", "operationId": "health_check_v1_health_build_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Health Check", "tags": [ "System" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations": { "get": { "description": "List all integrations for the current user.", "operationId": "list_integrations_v1_integrations_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/IntegrationResponse" }, "title": "Response List Integrations V1 Integrations Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Integrations", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations/{provider}": { "delete": { "description": "Disconnect an integration and revoke tokens.", "operationId": "disconnect_integration_v1_integrations__provider__delete", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect Integration", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations/{provider}/callback": { "post": { "description": "Exchange OAuth code for tokens and store integration.", "operationId": "integration_callback_v1_integrations__provider__callback_post", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCallbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Integration Callback", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations/{provider}/connect": { "get": { "description": "Get OAuth URL to connect a third-party service.", "operationId": "connect_integration_v1_integrations__provider__connect_get", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationConnectResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect Integration", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations/{provider}/status": { "get": { "description": "Get status of a specific integration.", "operationId": "get_integration_status_v1_integrations__provider__status_get", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Integration Status", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/integrations/{provider}/sync": { "post": { "description": "Trigger a manual sync for a connected integration.", "operationId": "trigger_sync_v1_integrations__provider__sync_post", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Sync", "tags": [ "Integrations" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/jobs": { "get": { "description": "List jobs with cursor-based pagination.\n\nSupports filtering by type and status.\nReturns next_cursor for pagination - pass it to the next request to get more results.\n\nArgs:\n job_type: Optional filter by job type\n status_filter: Optional filter by job status\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "list_jobs_v1_jobs_get", "parameters": [ { "in": "query", "name": "job_type", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/JobType" }, { "type": "null" } ], "title": "Job Type" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/JobStatus" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_JobResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Jobs", "tags": [ "Jobs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/jobs/{job_id}": { "delete": { "description": "Delete a job record.\n\nOnly completed, failed, or cancelled jobs can be deleted.", "operationId": "delete_job_v1_jobs__job_id__delete", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Job", "tags": [ "Jobs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get job status and details.\n\nPoll this endpoint to track job progress.", "operationId": "get_job_v1_jobs__job_id__get", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Job", "tags": [ "Jobs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/jobs/{job_id}/cancel": { "post": { "description": "Cancel a queued job.\n\nRunning work cannot be safely interrupted by the current executors, so the\nAPI rejects cancellation once execution has started instead of claiming a\ncancellation that cannot be honored.", "operationId": "cancel_job_v1_jobs__job_id__cancel_post", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Job", "tags": [ "Jobs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/knowledge-graph/context/{memory_id}": { "get": { "description": "Build context chain for a memory.\n\nRetrieves related memories via graph traversal to provide context.\nUseful for understanding the history and connections of a memory.\n\nArgs:\n memory_id: Target memory\n max_hops: Maximum graph traversal depth (1-5)\n min_confidence: Minimum relationship confidence (0-1)\n\nSECURITY: Verifies memory ownership before returning data.\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_memory_context_v1_knowledge_graph_context__memory_id__get", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "in": "query", "name": "max_hops", "required": false, "schema": { "default": 3, "maximum": 5, "minimum": 1, "title": "Max Hops", "type": "integer" } }, { "in": "query", "name": "min_confidence", "required": false, "schema": { "default": 0.5, "maximum": 1.0, "minimum": 0.0, "title": "Min Confidence", "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Memory Context", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/contradictions": { "get": { "description": "Find contradictions in user's knowledge graph.\n\nIf memory_id is provided, finds contradictions for that specific memory.\nOtherwise, returns all known contradictions.\n\nSECURITY: Verifies memory ownership when memory_id is provided.\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_contradictions_v1_knowledge_graph_contradictions_get", "parameters": [ { "in": "query", "name": "memory_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Id" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Contradictions", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/entities": { "get": { "description": "List entities in user's knowledge graph.\n\nOptionally filter by entity type (person, organization, location, etc.)\n\nP1-5 end-user isolation: pass `end_user_id` (or its alias `user_id`) to scope\nthe result to a single end-user, matching the isolation /search enforces. When\nomitted, account-level behavior is preserved (account-global / pre-backfill\nnodes with no end_user_id are included).\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "list_entities_v1_knowledge_graph_entities_get", "parameters": [ { "in": "query", "name": "entity_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" } }, { "description": "Filter entities by collection", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter entities by collection", "title": "Collection Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "End-user scope (P1-5 multi-tenant isolation). When set, only entities stamped with this end_user_id are returned. Aliases: user_id, enduser_id.", "in": "query", "name": "end_user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user scope (P1-5 multi-tenant isolation). When set, only entities stamped with this end_user_id are returned. Aliases: user_id, enduser_id.", "title": "End User Id" } }, { "description": "Synonym for end_user_id (end-user scope)", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Synonym for end_user_id (end-user scope)", "title": "User Id" } }, { "description": "Synonym for end_user_id", "in": "query", "name": "enduser_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Synonym for end_user_id", "title": "Enduser Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Entities", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Create a new entity in the knowledge graph.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "create_entity_v1_knowledge_graph_entities_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEntityRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Entity", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "kg_mutation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/entities/{entity_name}": { "delete": { "description": "Delete an entity and all its relationships from the knowledge graph.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "delete_entity_v1_knowledge_graph_entities__entity_name__delete", "parameters": [ { "in": "path", "name": "entity_name", "required": true, "schema": { "title": "Entity Name", "type": "string" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Entity", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get details about a specific entity.\n\nReturns:\n- Entity metadata\n- All relationships involving this entity\n- Timeline of mentions\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_entity_details_v1_knowledge_graph_entities__entity_name__get", "parameters": [ { "in": "path", "name": "entity_name", "required": true, "schema": { "title": "Entity Name", "type": "string" } }, { "description": "Scope related relationships + memory content to this collection (multi-tenant isolation). Omit for an account-level view.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope related relationships + memory content to this collection (multi-tenant isolation). Omit for an account-level view.", "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Entity Details", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/health": { "get": { "description": "Report real graph reachability without exposing infrastructure details.", "operationId": "health_check_v1_knowledge_graph_health_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Health Check", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/inference/paths": { "post": { "description": "Find all paths between two entities/memories in the knowledge graph.\n\nUseful for understanding how two pieces of information are connected.\n\nArgs:\n source_id: Starting entity/memory ID\n target_id: Target entity/memory ID\n max_hops: Maximum path length to search\n relation_types: Optional filter by relationship types\n\nSECURITY: Verifies ownership of both source and target memories.\nOnly shows paths within the user's own knowledge graph.\nTIER GATE: Requires Pro plan or higher.", "operationId": "find_paths_v1_knowledge_graph_inference_paths_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Find Paths", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_graph", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/inference/run": { "post": { "description": "Run inference engine to derive new knowledge from existing graph.\n\nUses transitive reasoning to infer new relationships:\n- If PART_OF(a,b) and PART_OF(b,c) then PART_OF(a,c)\n- If IS_A(a,b) and IS_A(b,c) then IS_A(a,c)\n- If CAUSES(a,b) and CAUSES(b,c) then ENABLES(a,c)\n\nArgs:\n relation_types: Which relationship types to consider for transitivity\n max_path_length: Maximum chain length for inference\n apply_rules: Whether to materialize inferred relationships in the graph\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "run_inference_engine_v1_knowledge_graph_inference_run_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Inference Engine", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_graph", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/query": { "post": { "description": "Query relationships that were valid at a specific time.\n\nEnables temporal reasoning: \"What did I know about X at time T?\"\n\nArgs:\n timestamp: Point in time to query (default: now)\n relation_type: Optional filter by relationship type\n limit: Maximum results to return\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "temporal_query_v1_knowledge_graph_query_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporalQueryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Temporal Query", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_graph", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/relationships": { "delete": { "description": "Delete a relationship between two entities.\n\nIf relationship_type is not specified, deletes all relationships between the entities.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "delete_relationship_v1_knowledge_graph_relationships_delete", "parameters": [ { "in": "query", "name": "source_entity", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Entity" } }, { "in": "query", "name": "target_entity", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Entity" } }, { "in": "query", "name": "relationship_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relationship Type" } }, { "in": "query", "name": "source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "in": "query", "name": "target", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "relationship_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relationship Id" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Relationship", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Create a relationship between two entities.\n\nBoth entities must exist and belong to the current user.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "create_relationship_v1_knowledge_graph_relationships_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRelationshipRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Relationship", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "kg_mutation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/relationships/{memory_id}": { "get": { "description": "Get all relationships for a specific memory.\n\nReturns:\n- Entities mentioned in the memory\n- Relationships between those entities\n- Related memories via shared entities\n\nSECURITY: Verifies memory ownership before returning data.\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_memory_relationships_v1_knowledge_graph_relationships__memory_id__get", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Memory Relationships", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/stats": { "get": { "description": "Get statistics about user's knowledge graph.\n\nFalls back to PostgreSQL-based stats when Neo4j is unavailable or empty.\n\nReturns:\n- Memory count\n- Entity count\n- Relationship count\n- Most connected entities\n- Relationship type distribution\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_graph_stats_v1_knowledge_graph_stats_get", "parameters": [ { "description": "Scope stats to a single collection (account-wide if omitted)", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope stats to a single collection (account-wide if omitted)", "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphStatsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Graph Stats", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/test-neo4j": { "get": { "description": "Debug endpoint to test Neo4j connection directly. Admin-only.", "operationId": "test_neo4j_connection_v1_knowledge_graph_test_neo4j_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Test Neo4J Connection", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/timeline/{entity_name}": { "get": { "description": "Get timeline of how facts about an entity changed over time.\n\nShows evolution of beliefs, preferences, and relationships.\n\nExample: Track how user's diet preferences evolved from\n\"vegetarian\" \u2192 \"pescatarian\" \u2192 \"omnivore\"\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_entity_timeline_v1_knowledge_graph_timeline__entity_name__get", "parameters": [ { "in": "path", "name": "entity_name", "required": true, "schema": { "title": "Entity Name", "type": "string" } }, { "description": "Scope the entity's relationships to this collection (multi-tenant isolation). Omit for an account-level view.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the entity's relationships to this collection (multi-tenant isolation). Omit for an account-level view.", "title": "Collection Id" } }, { "description": "Include raw memory-to-entity mention edges. Disabled by default so the timeline represents typed relationship events.", "in": "query", "name": "include_mentions", "required": false, "schema": { "default": false, "description": "Include raw memory-to-entity mention edges. Disabled by default so the timeline represents typed relationship events.", "title": "Include Mentions", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Entity Timeline", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/version": { "get": { "description": "Return the application version without exposing infrastructure.", "operationId": "version_check_v1_knowledge_graph_version_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Version Check", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/visualization/overview": { "get": { "description": "Get a high-level overview of the user's knowledge graph.\n\nReturns summary statistics and most connected nodes for initial visualization.\nFalls back to PostgreSQL memory data when Neo4j is empty.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_graph_overview_v1_knowledge_graph_visualization_overview_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Graph Overview", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/knowledge-graph/visualization/subgraph": { "post": { "description": "Get a subgraph suitable for visualization (D3.js, Cytoscape, etc.).\n\nReturns nodes and edges in a format suitable for graph visualization libraries.\n\nThe response includes:\n- nodes: List of {id, label, type, metadata}\n- edges: List of {source, target, type, weight}\n- center: The center node of the visualization\n\nSECURITY: Verifies memory ownership when center_memory_id is provided.\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_visualization_subgraph_v1_knowledge_graph_visualization_subgraph_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisualizationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Visualization Subgraph", "tags": [ "Knowledge Graph" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_graph", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/decisions": { "post": { "description": "Choose conservatively from tenant-scoped outcome evidence, or record an external choice with its propensity before the result is known. The caller must supply only actions its own authorization policy permits.", "operationId": "create_decision_receipt_v1_learning_decisions_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionReceiptRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recommend and record a decision receipt", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/decisions/{decision_id}": { "get": { "operationId": "get_decision_receipt_v1_learning_decisions__decision_id__get", "parameters": [ { "in": "path", "name": "decision_id", "required": true, "schema": { "title": "Decision Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a decision and its outcomes", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/decisions/{decision_id}/outcomes": { "post": { "description": "Append idempotent outcome evidence. Silence becomes censored\u2014not a negative label\u2014and corrections remain auditable.", "operationId": "record_decision_outcomes_v1_learning_decisions__decision_id__outcomes_post", "parameters": [ { "in": "path", "name": "decision_id", "required": true, "schema": { "title": "Decision Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report delayed outcomes", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/decisions/{decision_id}/proof": { "get": { "description": "Return deterministic receipt, evidence-manifest, and outcome digests. Digest consistency is not external attestation; signed connector attestation is reported separately when available.", "operationId": "get_decision_proof_v1_learning_decisions__decision_id__proof_get", "parameters": [ { "in": "path", "name": "decision_id", "required": true, "schema": { "title": "Decision Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the decision's evidence and outcome proof bundle", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/metrics": { "get": { "operationId": "list_metrics_v1_learning_metrics_get", "parameters": [ { "in": "query", "name": "policy_key", "required": false, "schema": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Policy Key" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List outcome metric definitions", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Define how a tenant-specific KPI is normalized, weighted, delayed, and guarded before it can influence a policy.", "operationId": "upsert_metric_v1_learning_metrics_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDefinitionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Define an outcome metric", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/policies/{policy_key}/evaluate": { "post": { "operationId": "evaluate_policy_v1_learning_policies__policy_key__evaluate_post", "parameters": [ { "in": "path", "name": "policy_key", "required": true, "schema": { "title": "Policy Key", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyEvaluationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run counterfactual policy-readiness checks", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/policies/{policy_key}/insights": { "get": { "operationId": "policy_insights_v1_learning_policies__policy_key__insights_get", "parameters": [ { "in": "path", "name": "policy_key", "required": true, "schema": { "title": "Policy Key", "type": "string" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, { "in": "query", "name": "action_key", "required": false, "schema": { "default": [], "items": { "type": "string" }, "title": "Action Key", "type": "array" } }, { "description": "Optional JSON object; POST /decisions is preferred for rich context", "in": "query", "name": "context", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional JSON object; POST /decisions is preferred for rich context", "title": "Context" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Explain what this tenant's policy has learned", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/learning/proof-key": { "get": { "description": "Return the public key and algorithm for offline verification of the DSSE/in-toto envelopes returned by decision proof endpoints.", "operationId": "get_proofloop_public_key_v1_learning_proof_key_get", "parameters": [ { "description": "Optional SHA-256 public-key fingerprint from an older proof", "in": "query", "name": "key_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "description": "Optional SHA-256 public-key fingerprint from an older proof", "title": "Key Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "summary": "Get the ProofLoop public verification key", "tags": [ "Outcome Memory" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media": { "get": { "description": "List user's media files.", "operationId": "list_media_v1_media_get", "parameters": [ { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "file_type", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaType" }, { "type": "null" } ], "title": "File Type" } }, { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProcessingStatus" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/search/transcript": { "get": { "description": "Search across all transcripts.", "operationId": "search_transcripts_v1_media_search_transcript_get", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "minLength": 2, "title": "Q", "type": "string" } }, { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Transcripts", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/stats/summary": { "get": { "description": "Get media statistics.", "operationId": "get_media_stats_v1_media_stats_summary_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Media Stats", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/supported/formats": { "get": { "description": "Get supported media formats.", "operationId": "get_supported_formats_v1_media_supported_formats_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Supported Formats", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/upload": { "post": { "description": "Upload audio or video file for transcription.\n\nSupported formats:\n- Video: MP4, AVI, MOV, MKV, WebM, FLV, WMV, M4V\n- Audio: MP3, WAV, M4A, OGG, FLAC, AAC, WMA, OPUS\n\nCollection routing is identical to /documents/upload \u2014 see that endpoint's\ndocstring. Responses include ``collection_auto_assigned`` so callers can\ndetect when the media silently defaulted to their user-default collection;\ncallers that want to forbid silent defaulting can send\n``X-Hebbrix-Require-Collection: true`` and receive HTTP 422 when\n``collection_id`` is missing.", "operationId": "upload_media_v1_media_upload_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_media_v1_media_upload_post" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/{media_id}": { "delete": { "description": "Delete source bytes and durably retire every derived artifact.", "operationId": "delete_media_v1_media__media_id__delete", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get media details.", "operationId": "get_media_v1_media__media_id__get", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } }, { "in": "query", "name": "include_transcript", "required": false, "schema": { "default": false, "title": "Include Transcript", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Update media file metadata.\n\nAllows updating:\n- name: Display name for the media file\n- description: Optional description text\n- collection_id: Move media to a different collection\n- tags: List of tags for organization", "operationId": "update_media_v1_media__media_id__patch", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/{media_id}/create-memories": { "post": { "description": "Create memory entries from transcript segments.", "operationId": "create_memories_from_media_v1_media__media_id__create_memories_post", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } }, { "in": "query", "name": "importance_threshold", "required": false, "schema": { "default": 0.3, "maximum": 1.0, "minimum": 0.0, "title": "Importance Threshold", "type": "number" } }, { "in": "query", "name": "create_summary", "required": false, "schema": { "default": true, "title": "Create Summary", "type": "boolean" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Memories From Media", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/{media_id}/segments": { "get": { "description": "Get transcript segments with timestamps.", "operationId": "get_segments_v1_media__media_id__segments_get", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } }, { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Segments", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/media/{media_id}/transcript": { "get": { "description": "Get full transcript.", "operationId": "get_transcript_v1_media__media_id__transcript_get", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Transcript", "tags": [ "Media Processing" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories": { "get": { "description": "List memories with cursor-based pagination.\n\nSupports filtering by collection_id.\nReturns next_cursor for pagination - pass it to the next request to get more results.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\nArgs:\n collection_id: Optional filter by collection\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "list_memories_v1_memories_get", "parameters": [ { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" } }, { "in": "query", "name": "end_user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End User Id" } }, { "in": "query", "name": "enduser_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enduser Id" } }, { "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "include_superseded", "required": false, "schema": { "default": false, "title": "Include Superseded", "type": "boolean" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCursorPage" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Memories", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Add memories with automatic fact extraction (Mem0-compatible).\n\nAccepts conversation messages or raw text and intelligently extracts\nstructured facts. Queries, greetings, and noise are filtered out.\n\n**Input Modes:**\n\n1. **Messages (recommended)** \u2014 send conversation turns, Hebbrix extracts facts:\n```json\n{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"I just moved to Austin and I love spicy food\"}\n ]\n}\n```\nResponse:\n```json\n{\n \"results\": [\n {\"id\": \"mem_xxx\", \"event\": \"ADD\", \"memory\": \"User moved to Austin\"},\n {\"id\": \"mem_yyy\", \"event\": \"ADD\", \"memory\": \"User loves spicy food\"}\n ]\n}\n```\n\n2. **Content + infer** \u2014 send raw text, Hebbrix extracts facts:\n```json\n{\"content\": \"I'm allergic to peanuts and work at Google\", \"infer\": true}\n```\n\n3. **Content + no infer** \u2014 store as-is (for bulk import/migration):\n```json\n{\"content\": \"User prefers dark mode\", \"infer\": false}\n```\n\n**Filtering:**\n- Tier 1: Embedding classifier rejects queries/questions (~30ms, no LLM cost)\n- Tier 2: LLM extracts only meaningful facts from content\n- Tier 3: Deduplication via content hash", "operationId": "add_memory_v1_memories_post", "parameters": [ { "in": "query", "name": "infer", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Infer" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryAdd" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryAddResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Memory", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_add", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/all": { "delete": { "description": "Delete ALL memories for the current user within the current source context.\n\n**WARNING:** This is a destructive operation that cannot be undone.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n- Only deletes memories from the specified source (app or api)\n\nArgs:\n collection_id: Optional - if provided, only delete memories from this collection.\n If not provided, deletes ALL memories across ALL collections for this source.\n\nReturns:\n BulkDeleteResponse with count of deleted memories", "operationId": "delete_all_memories_v1_memories_all_delete", "parameters": [ { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "description": "Preview how many memories WOULD be deleted without deleting anything.", "in": "query", "name": "dry_run", "required": false, "schema": { "default": false, "description": "Preview how many memories WOULD be deleted without deleting anything.", "title": "Dry Run", "type": "boolean" } }, { "description": "Optional safety confirmation. If provided it must equal 'all-memories'; otherwise the request is rejected. Omitting it preserves existing behavior.", "in": "header", "name": "X-Hebbrix-Confirm-Destructive", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional safety confirmation. If provided it must equal 'all-memories'; otherwise the request is rejected. Omitting it preserves existing behavior.", "title": "X-Hebbrix-Confirm-Destructive" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__memories__BulkDeleteResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete All Memories", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/batch": { "post": { "description": "Create multiple memories in a single request for high-throughput ingestion.\n\n**Data Isolation:**\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\n**Performance:** Up to 100 memories per request = 10-20x faster than individual calls.\n\n**Use Case:** Bulk data import, benchmark ingestion, migration from other systems.\n\nAll memories in the batch go to the same collection.\nUses bulk PostgreSQL insert and batch Celery task dispatch.\n\n**TIER GATE:** Requires Starter plan or higher.", "operationId": "create_memories_batch_v1_memories_batch_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMemoryResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Memories Batch", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1 per memory", "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_batch", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/bulk-delete": { "post": { "description": "Delete multiple memories by their IDs.\n\n**Data Isolation:**\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\nArgs:\n memory_ids: List of memory IDs to delete (max 500 per request)\n\nReturns:\n BulkDeleteResponse with count of deleted memories", "operationId": "delete_selected_memories_v1_memories_bulk_delete_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__memories__BulkDeleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__memories__BulkDeleteResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Selected Memories", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_add", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/jobs/status": { "post": { "description": "Poll a concurrent ingestion batch with one request and one SQL query.", "operationId": "get_memory_process_jobs_batch_v1_memories_jobs_status_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProcessJobBatchStatusRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProcessJobBatchStatusResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get up to 100 async memory-process job statuses", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_add", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/process": { "post": { "description": "Process conversation messages for automatic memory management.\n\nSend conversation turns and Hebbrix automatically:\n1. Extracts facts from the conversation\n2. Searches for conflicting existing memories\n3. Creates new memories, updates contradicted ones, or skips duplicates\n4. Propagates all changes across vectors, BM25, KG, tiers, and webhooks\n\n**Production mode is asynchronous by default:** fact extraction is\nLLM-bound, so an omitted or true `async_dispatch` returns `202` + a\n`job_id`, then the client polls `GET /v1/memories/jobs/{job_id}`. Explicit\n`async_dispatch=false` is reserved for low-throughput admin/debug/backfill\nworkflows that require the resulting events inline. Retrieval/search is\nunaffected and remains sub-second warm.\n\n**Enterprise Integration (3 lines):**\n```python\n# 1. Search for context\nmemories = hebbrix.search(query=user_message, user_id=end_user_id)\n# 2. Generate response with YOUR LLM\nresponse = your_llm.chat(messages + memories)\n# 3. Process for memory updates\nhebbrix.process(messages=[\n {\"role\": \"user\", \"content\": user_message},\n {\"role\": \"assistant\", \"content\": response}\n])\n```\n\n**Events Returned:**\n- `ADD` \u2014 New fact stored as a memory\n- `UPDATE` \u2014 Existing memory updated with corrected/refined info\n- `DELETE` \u2014 Contradicted memory removed, replaced by new fact\n- `NOOP` \u2014 Duplicate or already captured, no action taken", "operationId": "process_memories_v1_memories_process_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProcessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProcessResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Process Memories", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/raw": { "post": { "description": "Create a memory directly (raw storage, no fact extraction).\n\nUse this for bulk import, migration, or when you already have clean facts.\nFor smart fact extraction from conversations, use `POST /v1/memories` instead.", "operationId": "create_memory_v1_memories_raw_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryResponse" } } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Memory", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/search": { "get": { "description": "DEPRECATED \u2014 use POST /v1/search instead.\n\nThis GET endpoint runs the full multi-phase search arc with no fast-path,\ncandidate-pool cap, or response cache, so it is significantly slower (p50\n~1.3s, tail up to ~13s) than POST /v1/search (p50 ~0.46s, fast:true ~0.17s)\nand lacks deny-by-default scope isolation. It is kept for backward\ncompatibility only; new integrations should call POST /v1/search (set\n`fast:true` for the lowest latency). See the Deprecation/Sunset response\nheaders.\n\nSearch memories using hybrid search (vector + BM25 + AI reranking).\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)\n\nArgs:\n q: Search query\n collection_id: Optional filter by collection\n limit: Number of results (default: 10, max: 100)\n search_type: Type of search (hybrid, vector, bm25, graph)\n min_score: Optional override for the post-rerank relevance floor.\n Range 0.0\u20131.0. When omitted, the server picks 0.25 for narrow\n queries and 0.12 for structurally broad queries (multiple\n commas / conjunctions / >15 tokens \u2014 see\n `_is_broad_query` in hybrid_search.py). Lower values surface\n more tail-relevant results at the cost of precision; useful\n for multi-hop / multi-aspect queries where one embedding\n cannot land equally close to all facets.\n\nReturns:\n List of matching memories with relevance scores", "operationId": "search_memories_endpoint_v1_memories_search_get", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "title": "Q", "type": "string" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "search_type", "required": false, "schema": { "default": "hybrid", "title": "Search Type", "type": "string" } }, { "in": "query", "name": "min_score", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Score" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Search Memories Endpoint V1 Memories Search Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Memories Endpoint", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/{memory_id}": { "delete": { "description": "Delete a memory.\n\nPostgreSQL retirement and cross-store cleanup are delivered durably.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "delete_memory_v1_memories__memory_id__delete", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Memory", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get a specific memory by ID.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "get_memory_v1_memories__memory_id__get", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "format": "uuid", "title": "Memory Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryWithMetadata" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Memory", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Update a memory.\n\nSupports optimistic locking via If-Match header.\nInclude the ETag from GET response to prevent concurrent modifications.\nReturns 412 Precondition Failed if resource has been modified.\n\nData Isolation:\n- Send X-Hebbrix-Source: app header for Hebbrix App (Spaces)\n- Send X-Hebbrix-Source: api header for API Dashboard (Collections)", "operationId": "update_memory_v1_memories__memory_id__patch", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "in": "header", "name": "if-match", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "If-Match" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryWithMetadata" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } }, "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Memory", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memories/{memory_id}/history": { "get": { "description": "Version / supersede history for a memory. (2026-06-03 eval P2-13)\n\nWhen a contradiction is detected, Hebbrix stores the corrected fact as a new\nmemory and marks the old one `conflict_status='superseded'` with\n`superseded_by_id` pointing at the newer row. This endpoint walks that chain\n(oldest \u2192 newest) so callers can see how a fact evolved over time. The entry\nwith `is_current=true` is the live version.", "operationId": "get_memory_history_v1_memories__memory_id__history_get", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Memory History", "tags": [ "Memories" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-jobs/{job_id}": { "get": { "description": "Poll this endpoint when /v1/memories/process returned HTTP 202.\n\nReturns the full MemoryProcessResponse payload (inside `result`) when\nthe background job completes. Job records are retained for 1 hour then\nauto-expire.\n\nEnforces user isolation: only the caller who submitted the job can read\nits status. Non-owner lookups return 404 (not 403) to avoid leaking the\nexistence of other users' jobs.", "operationId": "get_memory_process_job_v1_memory_jobs__job_id__get", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProcessJobStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get async /v1/memories/process job status", "tags": [ "Memory Jobs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/memory-tools/consolidate": { "post": { "description": "Consolidate multiple memories into one.\n\nUses LLM to merge memories, archives originals.", "operationId": "consolidate_multiple_memories_v1_memory_tools_consolidate_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateMemoriesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consolidate Multiple Memories", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-tools/delete": { "delete": { "description": "Delete memory via agent tool.\n\nRemoves from all storage systems.", "operationId": "delete_memory_v1_memory_tools_delete_delete", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Memory", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-tools/insert": { "post": { "description": "Insert new memory via agent tool.\n\nCreates memory marked as agent-inserted.", "operationId": "insert_memory_v1_memory_tools_insert_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "202": { "description": "Durably committed and accepted for asynchronous processing. Poll Location/status_url until searchable or completed.", "headers": { "Location": { "description": "Relative status resource for the accepted write.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before polling the status resource.", "schema": { "minimum": 1, "type": "integer" } }, "X-Hebbrix-Index-Event": { "description": "Stable durable indexing event identifier.", "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Insert Memory", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "serialized by a PostgreSQL transaction lock; exactly one logical write", "fingerprint": "normalized request semantics + resolved collection", "implementation": "postgresql_transactional_outbox", "response_replay": "logical replay, not byte-for-byte; X-Idempotent-Replay is not emitted", "retention": "at least the lifecycle of the durable outbox record", "same_key_different_request": "409 idempotency_conflict", "same_key_same_request": "same logical resource/result; readiness may advance from accepted to searchable on a later replay", "scope": "authenticated account + key", "supported": true }, "x-hebbrix-operation-type": "memory_add", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-tools/replace": { "post": { "description": "Replace content in existing memory.\n\nAgent-controlled memory editing.", "operationId": "replace_memory_content_v1_memory_tools_replace_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Replace Memory Content", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_add", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-tools/rethink": { "post": { "description": "Reflect on and re-evaluate a memory.\n\nUses LLM to analyze memory accuracy and suggest improvements.", "operationId": "rethink_memory_v1_memory_tools_rethink_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RethinkMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rethink Memory", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/memory-tools/search": { "post": { "description": "Search memories (for agent self-access).\n\nAllows agent to search its own memory.", "operationId": "search_memories_v1_memory_tools_search_post", "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "title": "Query", "type": "string" } }, { "in": "query", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 5, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Memories", "tags": [ "Self-Editing Memory", "Self-Editing Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/mfa/backup-codes/regenerate": { "post": { "description": "Regenerate backup codes for the current user.\n\nThis invalidates all previous backup codes.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "regenerate_backup_codes_v1_mfa_backup_codes_regenerate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupCodesResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Regenerate Backup Codes", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/disable": { "post": { "description": "Disable MFA for the current user.\n\nMultiple verification options:\n- password: For local accounts with password\n- backup_code: Uses one of the saved backup codes\n- totp_code: Uses current authenticator app code\n- email_otp: Uses the emailed verification code\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "disable_mfa_v1_mfa_disable_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFADisableRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFADisableResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disable Mfa", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/disable/request-otp": { "post": { "description": "Request an email OTP to disable MFA.\n\nSends a 6-digit code to the user's email for verification.\nCode expires in 10 minutes.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "request_disable_otp_v1_mfa_disable_request_otp_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFADisableOTPResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Disable Otp", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/setup": { "post": { "description": "Initiate MFA setup for the current user.\n\nReturns a TOTP secret and QR code URI for authenticator apps.\nThe user must verify a code to complete setup.\n\nIf force_new=true, generates a new secret even if one exists.\nUse this if your authenticator has an outdated entry.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "initiate_mfa_setup_v1_mfa_setup_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MFASetupRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFASetupInitResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Initiate Mfa Setup", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/setup/request-otp": { "post": { "description": "Request an email OTP for MFA setup verification.\n\nAlternative to TOTP - sends a 6-digit code to the user's email.\nCode expires in 10 minutes.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "request_setup_otp_v1_mfa_setup_request_otp_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFASetupOTPResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Setup Otp", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/status": { "get": { "description": "Get MFA status for the current user.\n\nReturns whether MFA is enabled and how many backup codes remain.", "operationId": "get_mfa_status_v1_mfa_status_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFAStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Mfa Status", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/verify": { "post": { "description": "Verify an MFA code (TOTP, backup code, or email OTP).\n\nUsed during the login flow when MFA is required.\nSupports multiple verification methods:\n- totp: 6-digit code from authenticator app\n- backup: 8-character backup code\n- email_otp: 6-digit code sent to email\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "verify_mfa_v1_mfa_verify_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFAVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFAVerifyResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Verify Mfa", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/verify-setup": { "post": { "description": "Complete MFA setup by verifying a code.\n\nSupports two verification methods:\n- totp: 6-digit code from authenticator app (default)\n- email_otp: 6-digit code sent to email\n\nReturns backup codes that should be stored securely.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "verify_mfa_setup_v1_mfa_verify_setup_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFASetupVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFASetupCompleteResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Verify Mfa Setup", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/mfa/verify/request-otp": { "post": { "description": "Request an email OTP for MFA verification during login.\n\nSends a 6-digit code to the user's email for verification.\nCode expires in 10 minutes.\n\nSOC 2 Control: CC6.2 (Multi-factor authentication)", "operationId": "request_login_otp_v1_mfa_verify_request_otp_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFALoginOTPResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Login Otp", "tags": [ "Multi-Factor Auth" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/models": { "get": { "description": "List the models available to the authenticated key's tier (OpenAI shape).", "operationId": "list_models_v1_models_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Models", "tags": [ "Models", "Models" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies": { "get": { "description": "List all policy versions for an agent type with cursor-based pagination.\n\nReturns recent versions sorted by creation date (descending).\n\nArgs:\n agent_type: Agent type to list policies for (default: memory_manager)\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "list_policies_v1_policies_get", "parameters": [ { "in": "query", "name": "agent_type", "required": false, "schema": { "default": "memory_manager", "title": "Agent Type", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_PolicyVersion_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Policies", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/compare": { "post": { "description": "Compare two policy versions.\n\nReturns:\n- Metric differences (reward, latency, etc.)\n- Whether candidate is an improvement\n- Recommendation for promotion\n\nUseful before promoting a new policy to production.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "compare_policies_v1_policies_compare_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyComparisonRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyComparison" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compare Policies", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/promote": { "post": { "description": "Promote a policy version to production.\n\n**Requires admin role.**\n\nThis will:\n1. Archive the current production version\n2. Promote the specified version to production\n3. Update policy_version tracking\n\nUse with caution - ensure policy has been validated first.\n\nTIER GATE: Requires Pro plan or higher (plus admin role).", "operationId": "promote_policy_v1_policies_promote_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyPromotionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersion" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote Policy", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/rollback": { "post": { "description": "Rollback to a previous policy version.\n\n**Requires admin role.**\n\nThis will:\n1. Mark current production as rolled back\n2. Restore specified version to production\n3. Log rollback reason for audit\n\nUse when current production policy is performing poorly.\n\nTIER GATE: Requires Pro plan or higher (plus admin role).", "operationId": "rollback_policy_v1_policies_rollback_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRollbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersion" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rollback Policy", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/status": { "get": { "description": "Get comprehensive policy status for agent type.\n\nIncludes:\n- Current production version\n- Canary version (if any)\n- Latest candidate version\n- Recent version history\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_policy_status_v1_policies_status_get", "parameters": [ { "in": "query", "name": "agent_type", "required": false, "schema": { "default": "memory_manager", "title": "Agent Type", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Policy Status", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/train": { "post": { "description": "Trigger RL policy training.\n\nTraining requires a minimum number of user interactions (default: 100)\nto produce statistically meaningful policy improvements. Use force=true\nto train with fewer interactions (results may be less reliable).\n\nTraining runs asynchronously \u2014 check GET /policies/status for progress.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "trigger_policy_training_v1_policies_train_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Policy Training", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/{agent_type}/production": { "get": { "description": "Get current production policy version.\n\nReturns metadata about the policy currently serving production traffic.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_production_policy_v1_policies__agent_type__production_get", "parameters": [ { "in": "path", "name": "agent_type", "required": true, "schema": { "title": "Agent Type", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersion" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Production Policy", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/policies/{agent_type}/status": { "get": { "description": "Get comprehensive policy status for agent type.\n\nIncludes:\n- Current production version\n- Canary version (if any)\n- Latest candidate version\n- Recent version history\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "get_policy_status_v1_policies__agent_type__status_get", "parameters": [ { "in": "path", "name": "agent_type", "required": true, "schema": { "title": "Agent Type", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Policy Status", "tags": [ "RL Policy Management", "RL Policies" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures": { "get": { "description": "Get all procedures for current user.\n\nOptionally filter by category and active status. When ``collection_id`` is\nsupplied the list is STRICTLY scoped to that collection (cross-collection\nisolation) instead of returning the account-global set.", "operationId": "get_user_procedures_v1_procedures_get", "parameters": [ { "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "in": "query", "name": "active_only", "required": false, "schema": { "default": true, "title": "Active Only", "type": "boolean" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Procedures", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "post": { "description": "Create a new procedure.\n\nStores a learned procedure (IF-THEN rule) in procedural memory.", "operationId": "create_procedure_v1_procedures_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProcedureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures/feedback": { "post": { "description": "Record feedback for procedure execution.\n\nUpdates success rate and confidence based on feedback.", "operationId": "record_feedback_v1_procedures_feedback_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Feedback", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures/learn": { "post": { "description": "Learn new procedure from examples.\n\nAnalyzes examples and creates a new procedure.", "operationId": "learn_procedure_v1_procedures_learn_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearnProcedureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Learn Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures/match": { "post": { "description": "Find procedures matching given context.\n\nReturns procedures whose conditions match the context.", "operationId": "find_matching_procedures_v1_procedures_match_post", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "min_confidence", "required": false, "schema": { "default": 0.3, "maximum": 1.0, "minimum": 0.0, "title": "Min Confidence", "type": "number" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Run Id" } }, { "in": "query", "name": "include_global", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Global" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchProceduresRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Find Matching Procedures", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures/{procedure_id}": { "delete": { "description": "Idempotently delete one tenant-owned procedure and its executions.\n\nBoth an absent identifier and an identifier owned by another tenant return\n204. This provides safe idempotent replay without disclosing procedure\nexistence across tenant boundaries. Database foreign-key cascades remove\nprocedure executions; procedure matching reads the same source table, so\nno separate match index can retain a deleted procedure.", "operationId": "delete_procedure_v1_procedures__procedure_id__delete", "parameters": [ { "in": "path", "name": "procedure_id", "required": true, "schema": { "title": "Procedure Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get specific procedure by ID.\n\nReturns full procedure details including condition and action.", "operationId": "get_procedure_v1_procedures__procedure_id__get", "parameters": [ { "in": "path", "name": "procedure_id", "required": true, "schema": { "title": "Procedure Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "patch": { "description": "Update mutable fields on one tenant-owned procedure.", "operationId": "update_procedure_v1_procedures__procedure_id__patch", "parameters": [ { "in": "path", "name": "procedure_id", "required": true, "schema": { "title": "Procedure Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProcedureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/procedures/{procedure_id}/execute": { "post": { "description": "Execute a procedure.\n\nRuns the procedure with given input state and parameters.", "operationId": "execute_procedure_v1_procedures__procedure_id__execute_post", "parameters": [ { "in": "path", "name": "procedure_id", "required": true, "schema": { "title": "Procedure Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteProcedureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Procedure", "tags": [ "Procedural Memory", "Procedural Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/profile": { "delete": { "description": "Delete all profile facts for the current user.\n\nThis is a destructive operation. All static and dynamic facts will be removed.", "operationId": "delete_profile_v1_profile_delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Profile", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "get": { "description": "Get user profile (GET method).\n\nReturns full profile with static and dynamic facts.\nFor search integration, use POST /profile with a query.\n\n**Multi-tenant:** pass `collection_id` (or end-user `user_id`) to isolate one\nend-user's profile from account-global facts.", "operationId": "get_profile_via_get_v1_profile_get", "parameters": [ { "description": "Scope the returned profile to a single collection (multi-tenant isolation). Returns only facts tagged to this collection or derived from its memories. Omit for the full account-wide profile (legacy).", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the returned profile to a single collection (multi-tenant isolation). Returns only facts tagged to this collection or derived from its memories. Omit for the full account-wide profile (legacy).", "title": "Collection Id" } }, { "description": "Scope to a single END-USER (the user_id you tag memories with for multi-tenant apps). Returns only facts derived from that end-user's memories. Omit for the full account-wide profile.", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope to a single END-USER (the user_id you tag memories with for multi-tenant apps). Returns only facts derived from that end-user's memories. Omit for the full account-wide profile.", "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "app_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" } }, { "in": "query", "name": "namespace", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Profile Via Get", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Bulk update profile facts.\n\nAccepts a dictionary of fact_key \u2192 fact_value pairs.\nExisting facts are updated, new facts are created as static/other.\n\n**Multi-tenant scoping (2026-06-03):** two optional reserved keys \u2014\n- `collection_id`: tag written facts to a collection so they're isolated to\n that end-user (instead of becoming account-global). Reads scoped to the\n same collection return them; the account-wide read still sees everything.\n- `dry_run` (bool): preview what WOULD change without persisting.\n\nExample:\n PATCH /v1/profile\n {\"preferred_language\": \"Python\", \"collection_id\": \"coll_123\", \"dry_run\": true}", "operationId": "patch_profile_v1_profile_patch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Body", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch Profile", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Get user profile with optional search integration.\n\nThis is the main profile endpoint similar to SuperMemory's POST /v4/profile.\n\n**Features:**\n- Instant access to user profile facts (static + dynamic)\n- Optional search query integration\n- Combined context for AI assistants\n- Performance: ~50-100ms vs 200-500ms for multiple queries\n\n**Use Cases:**\n- AI assistants maintaining user preferences\n- Customer support with instant user history\n- Personalized content adaptation\n- Development tools with user context\n\n**Example:**\n```python\n# Get profile only\nPOST /v1/profile\n{\n \"include_static\": true,\n \"include_dynamic\": true\n}\n\n# Get profile + search results\nPOST /v1/profile\n{\n \"q\": \"job applications\",\n \"collection_id\": \"...\",\n \"search_limit\": 10\n}\n```", "operationId": "get_user_profile_endpoint_v1_profile_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Profile Endpoint", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/chat": { "post": { "description": "Dialectic reasoning via /chat path.", "operationId": "dialectic_chat_v1_profile_chat_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DialecticChatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DialecticChatResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dialectic Chat", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": "1-50 by served model", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "chat_nano", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/cleanup": { "post": { "description": "Clean up old dynamic facts.\n\nDynamic facts are temporary and should be cleaned up periodically.\nThis removes dynamic facts older than the specified number of days.", "operationId": "cleanup_old_dynamic_facts_v1_profile_cleanup_post", "parameters": [ { "in": "query", "name": "older_than_days", "required": false, "schema": { "default": 30, "maximum": 365, "minimum": 1, "title": "Older Than Days", "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cleanup Old Dynamic Facts", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/dialectic": { "post": { "description": "Dialectic reasoning via /dialectic path (alias for /chat).", "operationId": "dialectic_chat_alias_v1_profile_dialectic_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DialecticChatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DialecticChatResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dialectic Chat Alias", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 10, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_reason", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/facts": { "get": { "description": "Get all profile facts with optional filters.\n\nQuery parameters:\n- profile_type: Filter by \"static\" or \"dynamic\"\n- category: Filter by category\n- min_confidence: Minimum confidence threshold\n- collection_id: Scope to a single collection (multi-tenant isolation)\n- user_id: Scope to a single end-user (multi-tenant isolation)", "operationId": "get_all_facts_v1_profile_facts_get", "parameters": [ { "in": "query", "name": "profile_type", "required": false, "schema": { "anyOf": [ { "pattern": "^(static|dynamic)$", "type": "string" }, { "type": "null" } ], "title": "Profile Type" } }, { "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "in": "query", "name": "min_confidence", "required": false, "schema": { "default": 0.0, "maximum": 1.0, "minimum": 0.0, "title": "Min Confidence", "type": "number" } }, { "description": "Scope facts to a collection (multi-tenant isolation).", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope facts to a collection (multi-tenant isolation).", "title": "Collection Id" } }, { "description": "Scope facts to a single end-user (multi-tenant isolation).", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope facts to a single end-user (multi-tenant isolation).", "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "app_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" } }, { "in": "query", "name": "namespace", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get All Facts", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "post": { "description": "Add or update a profile fact.\n\nAllows manual addition/updating of user profile facts.\nAutomatically tracked in profile operations history.", "operationId": "add_profile_fact_v1_profile_facts_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__v1__endpoints__profile__AddFactRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Profile Fact", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/facts/by-id/{fact_id}": { "delete": { "description": "Delete a profile fact by its `id` (the value returned in GET /profile/facts).\n\nFIX (customer issue 7): the only delete route was keyed by `fact_key`, so\nDELETE /facts/{returned_id} matched the id as a key and 404'd even though the\nGET response surfaces an `id`. This route deletes by that id, scoped to the\ncaller's account. Uses ProfileManager.delete_fact_by_id so the profile cache\nis invalidated (the retest showed a raw delete left GET /profile serving the\nstale cached fact \u2014 a false success).", "operationId": "delete_profile_fact_by_id_v1_profile_facts_by_id__fact_id__delete", "parameters": [ { "in": "path", "name": "fact_id", "required": true, "schema": { "title": "Fact Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Profile Fact By Id", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/facts/{fact_key}": { "delete": { "description": "Delete a profile fact by key.\n\n**Multi-tenant:** pass end-user `user_id` to delete that end-user's fact;\nomit to target the account-global fact (end_user_id IS NULL).", "operationId": "delete_profile_fact_v1_profile_facts__fact_key__delete", "parameters": [ { "in": "path", "name": "fact_key", "required": true, "schema": { "title": "Fact Key", "type": "string" } }, { "description": "Scope the delete to a single end-user (multi-tenant isolation). Omit to target the account-global fact.", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the delete to a single end-user (multi-tenant isolation). Omit to target the account-global fact.", "title": "User Id" } }, { "description": "Scope the delete to one collection. Omit to target an account-global fact.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the delete to one collection. Omit to target an account-global fact.", "title": "Collection Id" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Profile Fact", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" }, "patch": { "description": "Partially update an existing profile fact.\n\nOnly provided fields are updated; omitted fields remain unchanged.\n\n**Multi-tenant:** pass end-user `user_id` to target that end-user's fact;\nomit to target the account-global fact (end_user_id IS NULL).", "operationId": "update_profile_fact_v1_profile_facts__fact_key__patch", "parameters": [ { "in": "path", "name": "fact_key", "required": true, "schema": { "title": "Fact Key", "type": "string" } }, { "description": "Scope the update to a single end-user (multi-tenant isolation). Omit to target the account-global fact.", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the update to a single end-user (multi-tenant isolation). Omit to target the account-global fact.", "title": "User Id" } }, { "description": "Scope the update to one collection. Omit to target an account-global fact.", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the update to one collection. Omit to target an account-global fact.", "title": "Collection Id" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchFactRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Profile Fact", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/history": { "get": { "description": "Get profile operation history.\n\nShows all additions, updates, and removals of profile facts.\nUseful for auditing and understanding profile evolution.", "operationId": "get_profile_history_v1_profile_history_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Profile History", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/snapshot": { "post": { "description": "Create a snapshot of the current profile.\n\nUseful for versioning and rollback capabilities.", "operationId": "create_profile_snapshot_v1_profile_snapshot_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Profile Snapshot", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/starters": { "get": { "description": "Get personalized conversation starters based on user profile.\n\nGenerates intelligent, context-aware questions and topics based on:\n- User's expertise and interests\n- Current projects and goals\n- Recent activities\n- Professional role\n\n**Example Response:**\n```json\n{\n \"starters\": [\n {\n \"question\": \"How is progress on building Hebbrix API going?\",\n \"context\": \"Based on your current project\",\n \"type\": \"llm_generated\"\n },\n ...\n ]\n}\n```", "operationId": "get_conversation_starters_v1_profile_starters_get", "parameters": [ { "in": "query", "name": "count", "required": false, "schema": { "default": 5, "maximum": 10, "minimum": 1, "title": "Count", "type": "integer" } }, { "in": "query", "name": "provider", "required": false, "schema": { "default": "openai", "pattern": "^(openai|anthropic)$", "title": "Provider", "type": "string" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "app_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" } }, { "in": "query", "name": "namespace", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Conversation Starters", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/stats": { "get": { "description": "Get profile statistics.\n\nReturns counts by type, category, and average confidence.", "operationId": "get_profile_stats_v1_profile_stats_get", "parameters": [ { "description": "Scope statistics to one owned collection", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope statistics to one owned collection", "title": "Collection Id" } }, { "description": "Scope statistics to one external end-user", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope statistics to one external end-user", "title": "User Id" } }, { "description": "Scope statistics to one observer/agent", "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope statistics to one observer/agent", "title": "Agent Id" } }, { "in": "query", "name": "app_id", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "App Id" } }, { "in": "query", "name": "namespace", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Namespace" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Profile Stats", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/profile/working-representation": { "post": { "description": "Get a compact working representation of the user.\n\nHebbrix working representation - an instant snapshot\nof the most relevant user context for injection into prompts.\n\n**Use Cases:**\n- Quick context injection into LLM prompts\n- Real-time personalization without full profile retrieval\n- Efficient context passing between microservices\n\n**Example Response:**\n```json\n{\n \"representation\": \"- role: Software Engineer\\n- expertise: Python, ML\\n- current_project: Building Hebbrix API\",\n \"fact_count\": 15,\n \"user_id\": \"...\",\n \"generated_at\": \"2024-01-15T10:30:00Z\"\n}\n```", "operationId": "get_working_representation_v1_profile_working_representation_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingRepresentationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Working Representation", "tags": [ "User Profiles" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/quality/auto-cleanup": { "post": { "description": "Trigger automatic cleanup of low-quality memories.\n\n This will:\n - Archive or delete memories below quality threshold\n - Consolidate similar low-importance memories\n - Free up storage and improve retrieval performance", "operationId": "trigger_auto_cleanup_v1_quality_auto_cleanup_post", "parameters": [ { "description": "Minimum quality to keep", "in": "query", "name": "min_quality_threshold", "required": false, "schema": { "default": 0.3, "description": "Minimum quality to keep", "maximum": 1, "minimum": 0, "title": "Min Quality Threshold", "type": "number" } }, { "description": "Preview changes without applying", "in": "query", "name": "dry_run", "required": false, "schema": { "default": true, "description": "Preview changes without applying", "title": "Dry Run", "type": "boolean" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Auto-Cleanup", "tags": [ "Memory Quality" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/quality/bulk": { "post": { "description": "Assess quality of multiple memories at once", "operationId": "assess_bulk_quality_v1_quality_bulk_post", "parameters": [ { "description": "List of memory IDs to assess", "in": "query", "name": "memory_ids", "required": true, "schema": { "description": "List of memory IDs to assess", "items": { "type": "string" }, "title": "Memory Ids", "type": "array" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkQualityResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Quality Assessment", "tags": [ "Memory Quality" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/quality/distribution": { "get": { "description": "Get distribution of memory quality across all user memories", "operationId": "get_quality_distribution_v1_quality_distribution_get", "parameters": [ { "description": "Filter by collection", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by collection", "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityDistribution" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Quality Distribution", "tags": [ "Memory Quality" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/quality/recommendations": { "get": { "description": "Get recommendations for improving overall memory quality", "operationId": "get_quality_recommendations_v1_quality_recommendations_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Quality Improvement Recommendations", "tags": [ "Memory Quality" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/quality/{memory_id}": { "get": { "description": "Get detailed quality assessment for a specific memory.\n\n Quality dimensions:\n - Content Quality: Length, informativeness, structure\n - Retrieval Performance: How often accessed, tier strength\n - Temporal Relevance: Recency and time-based importance\n - User Engagement: Feedback, access patterns\n\n Returns actionable recommendations for improvement.", "operationId": "assess_memory_quality_v1_quality__memory_id__get", "parameters": [ { "description": "Memory ID to assess", "in": "path", "name": "memory_id", "required": true, "schema": { "description": "Memory ID to assess", "format": "uuid", "title": "Memory Id", "type": "string" } }, { "description": "Include detailed breakdown", "in": "query", "name": "include_details", "required": false, "schema": { "default": true, "description": "Include detailed breakdown", "title": "Include Details", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityAssessment" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assess Memory Quality", "tags": [ "Memory Quality" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/release": { "get": { "description": "Identify the exact runtime and every compatible public artifact.", "operationId": "get_public_release_manifest_v1_release_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Get Public Release Manifest V1 Release Get", "type": "object" } } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Public Release Manifest", "tags": [ "Release Compatibility" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/rl/canary/rollback": { "post": { "description": "Immediately rollback canary deployment.\n\nInstantly switches all traffic back to baseline model.\n\nTIER GATE: Requires Enterprise plan (advanced deployment feature).", "operationId": "rollback_canary_v1_rl_canary_rollback_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rollback Canary", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/canary/start": { "post": { "description": "Start canary deployment of new RL policy.\n\nGradually ramps up traffic to new model with automatic rollback on failure.\n\nTIER GATE: Requires Enterprise plan (advanced deployment feature).", "operationId": "start_canary_deployment_v1_rl_canary_start_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanaryDeploymentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Canary Deployment", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/canary/status": { "get": { "description": "Get current canary deployment status.\n\nReturns traffic split, metrics, and deployment progress.\n\nTIER GATE: Requires Enterprise plan (advanced deployment feature).", "operationId": "get_canary_status_v1_rl_canary_status_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Canary Status", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/checkpoint/load": { "post": { "description": "Load model checkpoint.\n\nRestores both agents from saved checkpoint.\n\nAdministrative operation. Only artifacts created in Hebbrix's checkpoint\ndirectory can be loaded.", "operationId": "load_checkpoint_v1_rl_checkpoint_load_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Load Checkpoint", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/checkpoint/save": { "post": { "description": "Save current model checkpoint.\n\nSaves both agents and optimizer states.\n\nAdministrative operation. Checkpoints are process-wide model artifacts,\nnot tenant-owned resources.", "operationId": "save_checkpoint_v1_rl_checkpoint_save_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save Checkpoint", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/evaluate": { "post": { "description": "Evaluate a trained RL agent.\n\nRuns the agent on test queries and computes performance metrics.\n\nTIER GATE: Requires Pro plan or higher.", "operationId": "evaluate_agent_v1_rl_evaluate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "403": { "description": "rl_training requires the pro plan or the documented role. Error code: RL_EVALUATION_ENTITLEMENT_REQUIRED." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Evaluate Agent", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 10, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_reason", "x-hebbrix-plan-availability": { "error_code": "RL_EVALUATION_ENTITLEMENT_REQUIRED", "feature": "rl_training", "minimum_plan": "pro", "role": "account member" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/metrics": { "get": { "description": "Get training metrics summary.\n\nReturns current training statistics for both agents.\n\nRead-only metrics are available to Pro and higher accounts. Policy\ntraining, checkpoint mutation, promotion and rollback remain admin-only.", "operationId": "get_training_metrics_v1_rl_metrics_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "403": { "description": "rl_training requires the pro plan or the documented role. Error code: RL_METRICS_ENTITLEMENT_REQUIRED." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Training Metrics", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "error_code": "RL_METRICS_ENTITLEMENT_REQUIRED", "feature": "rl_training", "minimum_plan": "pro", "role": "account member" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/train/answer-agent": { "post": { "description": "Train Answer Agent.\n\nRuns training on query-memory selection data.\n\nAdministrative operation: training mutates a process-wide policy artifact.", "operationId": "train_answer_agent_v1_rl_train_answer_agent_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Train Answer Agent", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/train/both": { "post": { "description": "Train both Memory Manager and Answer Agent.\n\nRuns training for both agents sequentially.\n\nAdministrative operation: training mutates process-wide policy artifacts.", "operationId": "train_both_agents_v1_rl_train_both_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Train Both Agents", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/rl/train/memory-manager": { "post": { "description": "Train Memory Manager agent.\n\nRuns PPO training on collected trajectories.\nReturns a job_id for tracking progress.\n\nAdministrative operation: training mutates a process-wide policy artifact.", "operationId": "train_memory_manager_v1_rl_train_memory_manager_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Train Memory Manager", "tags": [ "RL Training", "RL Training" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/search": { "post": { "description": "Search memories using hybrid retrieval.\n\nCombines:\n- Dense vector search (Qdrant)\n- Sparse BM25 search\n- Knowledge graph traversal (Neo4j)\n\nResults are re-ranked using ONNX neural reranker and time decay.\n\nPhase 4 Fix 4.5: Returns X-Search-Degraded header when search is degraded.", "operationId": "search_memories_endpoint_v1_search_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Require-Collection", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Require-Collection" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Memories Endpoint", "tags": [ "Search" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/search/advanced": { "post": { "description": "Advanced search with additional filtering and boosting capabilities.\n\nThis endpoint provides more control over search behavior including:\n- Minimum score thresholds\n- Recency and importance boosting\n- Entity-based filtering\n- Date range filtering\n\nMore computationally expensive than basic search.\n\nPhase 4 Fix 4.5: Returns X-Search-Degraded header when search is degraded.", "operationId": "advanced_search_memories_v1_search_advanced_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Advanced Search Memories", "tags": [ "Search" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/search/graph": { "post": { "description": "Search the knowledge graph for entities and relationships.\n\nAccepts query as URL parameter (?query=...) or in JSON body ({\"query\": \"...\"}).\n\nFirst searches for entities matching the query, then returns\nthe subgraph around the most relevant entity.", "operationId": "search_knowledge_graph_v1_search_graph_post", "parameters": [ { "in": "query", "name": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "in": "query", "name": "depth", "required": false, "schema": { "default": 2, "maximum": 5, "minimum": 1, "title": "Depth", "type": "integer" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GraphSearchRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Knowledge Graph", "tags": [ "Search" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_graph", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/search/reason": { "post": { "description": "Perform reasoning over memories using LLM.\n\nRetrieves relevant memories and generates a comprehensive answer\nusing the configured LLM provider (Gemini, OpenAI, or Claude).", "operationId": "reason_with_memories_v1_search_reason_post", "parameters": [ { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasoningRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasoningResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reason With Memories", "tags": [ "Search" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 10, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search_reason", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/search/similar/{memory_id}": { "get": { "description": "Find similar memories to a given memory.\n\nUses vector similarity search to find memories with similar embeddings.\nResults are HARD-scoped to the source memory's end-user (and to `user_id`\nwhen supplied) so similar-search can never cross end-user boundaries (P0-2).", "operationId": "find_similar_memories_v1_search_similar__memory_id__get", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "End-user scope (multi-tenant isolation)", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user scope (multi-tenant isolation)", "title": "User Id" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" } }, { "description": "Synonym for user_id", "in": "query", "name": "end_user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Synonym for user_id", "title": "End User Id" } }, { "description": "Synonym for user_id", "in": "query", "name": "enduser_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Synonym for user_id", "title": "Enduser Id" } }, { "in": "header", "name": "X-Hebbrix-Source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Hebbrix-Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Find Similar Memories", "tags": [ "Search" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "ga" } }, "/v1/slo": { "get": { "description": "Public engineering objectives, configured limits, and scoped observations.", "operationId": "get_slo_v1_slo_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Published Service Level Objectives", "tags": [ "SLO" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/stats/stats": { "get": { "description": "Get current platform-wide counts for administrators.", "operationId": "get_system_stats_v1_stats_stats_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStatsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get System Stats", "tags": [ "Stats" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/support/admin/tickets": { "get": { "description": "Admin: list all tickets with optional filters.", "operationId": "admin_list_tickets_v1_support_admin_tickets_get", "parameters": [ { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "category_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category Filter" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin List Tickets", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/support/admin/tickets/{ticket_id}": { "patch": { "description": "Admin: update ticket status. Syncs to HubSpot automatically.", "operationId": "admin_update_ticket_v1_support_admin_tickets__ticket_id__patch", "parameters": [ { "in": "path", "name": "ticket_id", "required": true, "schema": { "title": "Ticket Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTicketRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Update Ticket", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/support/tickets": { "get": { "description": "List all tickets submitted by the logged-in user.", "operationId": "list_my_tickets_v1_support_tickets_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TicketResponse" }, "title": "Response List My Tickets V1 Support Tickets Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List My Tickets", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "post": { "description": "Submit a support ticket. Works for both logged-in users and anonymous visitors.\nSyncs automatically to HubSpot CRM and sends a confirmation email.", "operationId": "submit_ticket_v1_support_tickets_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Ticket", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/support/tickets/{ticket_id}": { "get": { "description": "Get a single ticket \u2014 only accessible by the ticket owner.", "operationId": "get_my_ticket_v1_support_tickets__ticket_id__get", "parameters": [ { "in": "path", "name": "ticket_id", "required": true, "schema": { "title": "Ticket Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Ticket", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/support/webhooks/tawkto": { "post": { "description": "Receive events from Tawk.to (chat started, ticket created, chat ended).\nTawk.to sends a POST with JSON payload. We verify the signature if a\nsecret is configured, then create a support ticket from the conversation.\n\nConfigure this URL in Tawk.to:\nAdministration \u2192 Integrations \u2192 Webhooks \u2192 Add webhook\nURL: https://api.hebbrix.com/v1/support/webhooks/tawkto", "operationId": "tawkto_webhook_v1_support_webhooks_tawkto_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "TawkSignature": [] } ], "summary": "Tawkto Webhook", "tags": [ "Customer Support" ], "x-hebbrix-data-scope": { "authorization": "signature verified before processing", "classification": "signed_webhook" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts": { "post": { "description": "Add temporal fact to knowledge graph.\n\nCreates a bi-temporal fact with validity period and observation time.", "operationId": "add_fact_v1_temporal_facts_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__routes__temporal__AddFactRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Fact", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts/conflicts": { "get": { "description": "Get conflicting facts.\n\nReturns facts with overlapping validity periods that may conflict.", "operationId": "get_conflicts_v1_temporal_facts_conflicts_get", "parameters": [ { "in": "query", "name": "subject", "required": true, "schema": { "title": "Subject", "type": "string" } }, { "in": "query", "name": "predicate", "required": true, "schema": { "title": "Predicate", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Conflicts", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts/history": { "get": { "description": "Get complete history of facts.\n\nReturns all facts (current and past) for subject-predicate pair.", "operationId": "get_fact_history_v1_temporal_facts_history_get", "parameters": [ { "in": "query", "name": "subject", "required": true, "schema": { "title": "Subject", "type": "string" } }, { "in": "query", "name": "predicate", "required": true, "schema": { "title": "Predicate", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Fact History", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts/invalidate": { "post": { "description": "Invalidate a fact.\n\nSets valid_until to mark the fact as no longer true.", "operationId": "invalidate_fact_v1_temporal_facts_invalidate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidateFactRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invalidate Fact", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts/query-at-time": { "post": { "description": "Query facts at specific point in time.\n\nReturns facts that were valid at the given timestamp.", "operationId": "query_at_time_v1_temporal_facts_query_at_time_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAtTimeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Query At Time", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 2, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "search", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/temporal/facts/{fact_id}": { "delete": { "description": "Permanently remove one fact from this tenant's temporal ledger.\n\n``fact_id`` is the stable ID returned by :func:`add_fact`. The tenant is\nderived exclusively from authentication, so an ID from another account is\nindistinguishable from an already-deleted ID. Deletion is idempotent and is\ndelivered to every configured graph projection through the durable manual\nmutation outbox.", "operationId": "delete_fact_v1_temporal_facts__fact_id__delete", "parameters": [ { "in": "path", "name": "fact_id", "required": true, "schema": { "maxLength": 128, "minLength": 1, "title": "Fact Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Fact", "tags": [ "Temporal Knowledge", "Temporal Knowledge" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/config": { "get": { "description": "Get user's tier configuration.\n\nReturns the current configuration for the three-tier memory system.\nIf no configuration exists, default values are returned.", "operationId": "get_tier_config_v1_tiers_config_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierConfigResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tier Config", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "put": { "description": "Update user's tier configuration.\n\nAllows customization of:\n- Tier retention policies\n- Promotion/demotion thresholds\n- Consolidation settings", "operationId": "update_tier_config_v1_tiers_config_put", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierConfigUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierConfigResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Tier Config", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/consolidate": { "post": { "description": "Manually trigger memory consolidation.\n\nConsolidates short-term memories into mid-term summaries.", "operationId": "trigger_consolidation_v1_tiers_consolidate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Consolidation", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/memories": { "get": { "description": "List memories in tier system with cursor-based pagination.\n\nOptionally filter by tier (short_term, mid_term, long_term).\n\nArgs:\n tier: Filter by tier (short_term, mid_term, long_term)\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "list_tiered_memories_v1_tiers_memories_get", "parameters": [ { "in": "query", "name": "tier", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_TieredMemoryResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Tiered Memories", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/memories/{memory_id}/tier": { "delete": { "description": "Remove a memory from the tier system.\n\nThe memory still exists in the main memories table,\nbut will no longer be tracked in the tier system.", "operationId": "remove_from_tier_system_v1_tiers_memories__memory_id__tier_delete", "parameters": [ { "in": "path", "name": "memory_id", "required": true, "schema": { "title": "Memory Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove From Tier System", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/promote": { "post": { "description": "Manually trigger tier promotion checks.\n\nIf memory_id is provided, checks only that memory.\nOtherwise, checks all user's memories for promotion eligibility.", "operationId": "trigger_promotions_v1_tiers_promote_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Promotions", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/stats": { "get": { "description": "Get user's tier statistics.\n\nReturns:\n- Memory counts per tier\n- Average strength scores\n- Recent tier transitions", "operationId": "get_tier_stats_v1_tiers_stats_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierStatsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tier Stats", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/tiers/transitions": { "get": { "description": "Get recent tier transitions for user's memories with cursor-based pagination.\n\nShows promotion and demotion history.\n\nArgs:\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "get_tier_transitions_v1_tiers_transitions_get", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_TransitionResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tier Transitions", "tags": [ "Memory Tiers" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/token-packs": { "get": { "description": "List available token packs and current balance.\n\nOnly paid tier users can purchase token packs.\nFree tier users will see upgrade_required=True.", "operationId": "list_token_packs_v1_token_packs_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPacksResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Token Packs", "tags": [ "Token Packs", "Token Packs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/token-packs/history": { "get": { "description": "Get token pack purchase history for the current user.", "operationId": "get_purchase_history_v1_token_packs_history_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseHistoryResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Purchase History", "tags": [ "Token Packs", "Token Packs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/token-packs/purchase/{pack_id}": { "post": { "description": "Create a Stripe checkout session for token pack purchase.\n\nOnly available to paid tier users. Free tier must upgrade first.", "operationId": "purchase_token_pack_v1_token_packs_purchase__pack_id__post", "parameters": [ { "in": "path", "name": "pack_id", "required": true, "schema": { "title": "Pack Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Purchase Token Pack", "tags": [ "Token Packs", "Token Packs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/token-packs/quota": { "get": { "description": "Get detailed token quota information for the current user.\n\nReturns subscription quota, purchased tokens, and usage summary.", "operationId": "get_token_quota_v1_token_packs_quota_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Token Quota", "tags": [ "Token Packs", "Token Packs" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/token-packs/webhook": { "post": { "description": "Handle Stripe webhook for completed token pack payments.\n\nThis endpoint is called by Stripe when a payment is completed.\nIt credits the purchased tokens to the user's account.", "operationId": "stripe_webhook_v1_token_packs_webhook_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "StripeSignature": [] } ], "summary": "Stripe Webhook", "tags": [ "Token Packs", "Token Packs" ], "x-hebbrix-data-scope": { "authorization": "signature verified before processing", "classification": "signed_webhook" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import": { "get": { "description": "List imported URLs.", "operationId": "list_imports_v1_url_import_get", "parameters": [ { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Skip", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "source_type", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/URLSourceType" }, { "type": "null" } ], "title": "Source Type" } }, { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportStatus" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Imports", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/import": { "post": { "description": "Import content from a URL.\n\nSupports:\n- Articles and blog posts\n- Twitter/X tweets and threads\n- YouTube videos (metadata)\n- Generic web pages", "operationId": "import_url_v1_url_import_import_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/URLImportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Import Url", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/import/batch": { "post": { "description": "Import multiple URLs at once.", "operationId": "import_urls_batch_v1_url_import_import_batch_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchURLImportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Import Urls Batch", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/stats/summary": { "get": { "description": "Get import statistics.", "operationId": "get_import_stats_v1_url_import_stats_summary_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Import Stats", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/supported/sources": { "get": { "description": "Get supported URL sources.", "operationId": "get_supported_sources_v1_url_import_supported_sources_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Supported Sources", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/{import_id}": { "delete": { "description": "Delete imported content and durably retire every derived memory.", "operationId": "delete_import_v1_url_import__import_id__delete", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "title": "Import Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Import", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get import details.", "operationId": "get_import_v1_url_import__import_id__get", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "title": "Import Id", "type": "string" } }, { "in": "query", "name": "include_content", "required": false, "schema": { "default": false, "title": "Include Content", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Import", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/url-import/{url_id}/create-memories": { "post": { "description": "Convert imported URL content to searchable memories.\n\nThis endpoint takes the extracted content from an imported URL and creates\nMemory objects that can be searched via the RAG assistant.", "operationId": "create_memories_from_url_v1_url_import__url_id__create_memories_post", "parameters": [ { "in": "path", "name": "url_id", "required": true, "schema": { "title": "Url Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Memories From Url", "tags": [ "URL Import" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": "10 per MB", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "document_upload", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage": { "get": { "description": "Get API usage overview. Alias for /usage/overview.", "operationId": "get_usage_overview_v1_usage_get", "parameters": [ { "description": "Number of days to include", "in": "query", "name": "days", "required": false, "schema": { "default": 30, "description": "Number of days to include", "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageOverview" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Usage", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/api-key/{api_key_id}": { "get": { "description": "Get detailed usage statistics for a specific API key", "operationId": "get_api_key_usage_v1_usage_api_key__api_key_id__get", "parameters": [ { "in": "path", "name": "api_key_id", "required": true, "schema": { "title": "Api Key Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyUsage" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get API Key Usage", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/billing": { "get": { "description": "Get complete billing and token usage transparency - see exactly what you're charged", "operationId": "get_billing_transparency_v1_usage_billing_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingTransparencyResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Billing Transparency", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/credit-usage": { "get": { "description": "Returns detailed usage from the credit ledger for the current billing period", "operationId": "get_credit_usage_v1_usage_credit_usage_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credit Ledger Usage", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/credits": { "get": { "description": "Return the caller's real-time credit balance and plan for budgeting /\nquota alarms.", "operationId": "get_credit_balance_v1_usage_credits_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get remaining credit / quota balance", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/export": { "get": { "description": "Export usage data as JSON for external analysis", "operationId": "export_usage_data_v1_usage_export_get", "parameters": [ { "description": "Number of days to export", "in": "query", "name": "days", "required": false, "schema": { "default": 30, "description": "Number of days to export", "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } }, { "description": "Export format (json only currently)", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "description": "Export format (json only currently)", "title": "Format", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Usage Data", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/history": { "get": { "description": "Paginated history of API requests for the authenticated user.", "operationId": "get_usage_history_v1_usage_history_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "Filter results to the last N days (1-365). Omit for all time.", "in": "query", "name": "days", "required": false, "schema": { "anyOf": [ { "maximum": 365, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Filter results to the last N days (1-365). Omit for all time.", "title": "Days" } }, { "in": "query", "name": "api_key_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Id" } }, { "in": "query", "name": "endpoint", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Endpoint" } }, { "in": "query", "name": "status_code", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecentRequest" }, "title": "Response Get Usage History V1 Usage History Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Usage History", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/managed-balance": { "get": { "description": "Returns current USD credit balance for managed AI usage", "operationId": "get_managed_balance_v1_usage_managed_balance_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Managed AI Credit Balance", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/memory-quota": { "get": { "description": "Get current memory usage and quota limits for the authenticated user", "operationId": "get_memory_quota_v1_usage_memory_quota_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryQuotaResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Memory Quota", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/overview": { "get": { "description": "Get complete API usage overview for the dashboard", "operationId": "get_usage_overview_v1_usage_overview_get", "parameters": [ { "description": "Number of days to include", "in": "query", "name": "days", "required": false, "schema": { "default": 30, "description": "Number of days to include", "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageOverview" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Usage Overview", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/quota": { "get": { "description": "Get complete usage and quota information including memories, API calls, tokens, searches, and chat completions", "operationId": "get_usage_quota_v1_usage_quota_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQuotaResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Complete Usage Quota", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/recent": { "get": { "description": "Get list of most recent API requests", "operationId": "get_recent_requests_v1_usage_recent_get", "parameters": [ { "description": "Number of requests to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Number of requests to return", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Filter by API key", "in": "query", "name": "api_key_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by API key", "title": "Api Key Id" } }, { "description": "Filter by endpoint pattern", "in": "query", "name": "endpoint", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by endpoint pattern", "title": "Endpoint" } }, { "description": "Filter by status code", "in": "query", "name": "status_code", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter by status code", "title": "Status Code" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecentRequest" }, "title": "Response Get Recent Requests V1 Usage Recent Get", "type": "array" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Recent Requests", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/usage/spending": { "get": { "description": "Accumulated credit usage for the current calendar month, grouped by operation_type with estimated USD cost. Works across all tiers.", "operationId": "get_spending_summary_v1_usage_spending_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Month-to-date spending summary", "tags": [ "API Usage" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/users/me": { "delete": { "description": "Delete the current user account.\n\nSoft-deletes the user + their collections + their memories, with a 90-day\nretention window before permanent deletion (GDPR Article 17). The account\ncan be restored within the retention window via `POST /v1/gdpr/restore-account`.\n\n2026-05-11: Previously this called `db.delete(current_user)` which produced\nHTTP 500 because users have foreign-key references from a dozen child\ntables (api_usage_logs, memory_tier_transitions, credit_balances, etc.)\nwithout ON DELETE CASCADE. The fix routes to the same soft-delete path\nthat `POST /v1/gdpr/delete-account` already uses, so DELETE here matches\nthe customer-facing GDPR flow and stops 500-ing.", "operationId": "delete_current_user_v1_users_me_delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Current User", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get current user profile.", "operationId": "get_current_user_profile_v1_users_me_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Current User Profile", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "patch": { "description": "Update current user profile.", "operationId": "update_current_user_v1_users_me_patch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Current User", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/users/me/capabilities": { "get": { "description": "Return the authoritative plan/role capability matrix for this account.", "operationId": "get_current_user_capabilities_v1_users_me_capabilities_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Get Current User Capabilities V1 Users Me Capabilities Get", "type": "object" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Current User Capabilities", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/users/me/model-preference": { "get": { "description": "Get the user's preferred model.\n\nReturns the saved model preference (starter+ only) and available models for the user's tier.", "operationId": "get_model_preference_v1_users_me_model_preference_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Model Preference", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "put": { "description": "Set the user's preferred model (starter+ only).\n\nThe chosen model is used as the default when no model is specified in chat requests.\nFree tier users cannot set a preference \u2014 they are always on gpt-5-nano.\nPass model=null to clear the preference and revert to the tier default.", "operationId": "set_model_preference_v1_users_me_model_preference_put", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPreferenceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Model Preference", "tags": [ "Users" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/waitlist/join": { "post": { "description": "Join the waitlist for early access.\n\nThis endpoint is public and does not require authentication.\nIt captures email and optional metadata for early access requests.", "operationId": "join_waitlist_v1_waitlist_join_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistJoinRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistJoinResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Join Waitlist", "tags": [ "Waitlist" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": "unmapped; request is rejected when strict billing is enabled", "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "unmapped", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/waitlist/stats": { "get": { "description": "Get public waitlist statistics.\n\nReturns total signups and recent activity for social proof.", "operationId": "get_waitlist_stats_v1_waitlist_stats_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistStatsResponse" } } }, "description": "Successful Response" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Get Waitlist Stats", "tags": [ "Waitlist" ], "x-hebbrix-data-scope": { "authorization": "none", "classification": "public" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks": { "get": { "description": "List webhooks with cursor-based pagination.\n\nReturns next_cursor for pagination - pass it to the next request to get more results.\nSecret is hidden in list responses for security.\n\nArgs:\n cursor: Cursor from previous page (for pagination)\n limit: Number of items per page (default: 50, max: 100)", "operationId": "list_webhooks_v1_webhooks_get", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorPage_WebhookResponse_" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Webhooks", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "post": { "description": "Register a new webhook.\n\nReturns webhook configuration including the HMAC secret for signature verification.", "operationId": "create_webhook_v1_webhooks_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Webhook", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/failures": { "get": { "description": "List webhook delivery failures (DLQ rows) for the current user.\n\nFilters:\n - status_filter: pending_retry | replayed | abandoned\n - webhook_id: restrict to one webhook subscription", "operationId": "list_webhook_failures_v1_webhooks_failures_get", "parameters": [ { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "webhook_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookFailureListResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Webhook Failures", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/failures/{failure_id}/abandon": { "post": { "description": "Mark a DLQ row as abandoned \u2014 won't show up in pending_retry lists.", "operationId": "abandon_webhook_failure_v1_webhooks_failures__failure_id__abandon_post", "parameters": [ { "in": "path", "name": "failure_id", "required": true, "schema": { "title": "Failure Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookFailureReplayResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Abandon Webhook Failure", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/failures/{failure_id}/replay": { "post": { "description": "Stage a durable retry for a previously failed webhook delivery.\n\nThe DLQ row is marked `replayed` (regardless of whether THIS attempt\neventually succeeds \u2014 the row's status records that we tried again).\nFuture failures of the replay will land as NEW DLQ rows.", "operationId": "replay_webhook_failure_v1_webhooks_failures__failure_id__replay_post", "parameters": [ { "in": "path", "name": "failure_id", "required": true, "schema": { "title": "Failure Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookFailureReplayResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Replay Webhook Failure", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/stripe": { "post": { "description": "Handle all Stripe webhooks.\n\nThis endpoint receives and routes all Stripe webhook events.\nEvents are verified using the Stripe signature.", "operationId": "handle_stripe_webhook_v1_webhooks_stripe_post", "parameters": [ { "in": "header", "name": "Stripe-Signature", "required": true, "schema": { "title": "Stripe-Signature", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "StripeSignature": [] } ], "summary": "Handle Stripe Webhook", "tags": [ "Stripe Webhooks" ], "x-hebbrix-data-scope": { "authorization": "signature verified before processing", "classification": "signed_webhook" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/{webhook_id}": { "delete": { "description": "Delete a webhook.", "operationId": "delete_webhook_v1_webhooks__webhook_id__delete", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Webhook", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "get": { "description": "Get webhook details by ID.\n\nThe HMAC secret/signing_secret is intentionally masked \u2014 it's only ever\nreturned once at creation (POST /v1/webhooks) and after rotation\n(POST /v1/webhooks/{id}/rotate-secret). Re-disclosing it on read would\nlet anyone who later compromises the API key escalate to forging\ndelivery signatures.", "operationId": "get_webhook_v1_webhooks__webhook_id__get", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Webhook", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "patch": { "description": "Partial update of webhook configuration (PATCH alias of PUT).", "operationId": "update_webhook_patch_v1_webhooks__webhook_id__patch", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Webhook Patch", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" }, "put": { "description": "Update webhook configuration.", "operationId": "update_webhook_v1_webhooks__webhook_id__put", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Webhook", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/{webhook_id}/rotate-secret": { "post": { "description": "Rotate the HMAC secret for a webhook.\n\n**Security best practice**: Rotate secrets regularly or when compromised.\n\nThis will:\n1. Generate a new HMAC secret\n2. Update the webhook configuration\n3. Return the new secret (store it securely!)\n\n**IMPORTANT**: Update your webhook receiver to use the new secret immediately.\nThe old secret will no longer be valid after this operation.\n\nUse cases:\n- Regular security rotation (recommended: every 90 days)\n- Secret has been compromised or exposed\n- Team member with access has left\n- Compliance requirements", "operationId": "rotate_webhook_secret_v1_webhooks__webhook_id__rotate_secret_post", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretRotateResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rotate Webhook Secret", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/webhooks/{webhook_id}/test": { "post": { "description": "Test webhook delivery with a ping event.\n\nSends a test payload to verify the webhook is working.", "operationId": "test_webhook_v1_webhooks__webhook_id__test_post", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Test Webhook", "tags": [ "Webhooks" ], "x-hebbrix-data-scope": { "authorization": "authenticated account authorization before data access", "classification": "authenticated_account" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/add": { "post": { "description": "Add item to working memory buffer.\n\nStores conversational turn in short-term buffer.", "operationId": "add_to_working_memory_v1_working_memory_add_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddToWorkingMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add To Working Memory", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/clear/{session_id}": { "delete": { "description": "Clear working memory buffer for session.\n\nRemoves all items from buffer (does not affect long-term memory).", "operationId": "clear_working_memory_v1_working_memory_clear__session_id__delete", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear Working Memory", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/compress/{session_id}": { "post": { "description": "Compress working memory to summary.\n\nUses LLM to create 2-3 sentence summary of buffer.", "operationId": "compress_working_memory_v1_working_memory_compress__session_id__post", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compress Working Memory", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/consolidate": { "post": { "description": "Consolidate working memory to long-term storage.\n\nExtracts important facts and creates long-term memories.", "operationId": "consolidate_to_long_term_v1_working_memory_consolidate_post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/backend__api__routes__working_memory__ConsolidateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateResponse" } } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateResponse" } } }, "description": "Facts and their durable index event committed; search indexing continues asynchronously.", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consolidate To Long Term", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 5, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_process", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/context/{session_id}": { "get": { "description": "Get current working memory context for session.\n\nReturns recent conversation turns and optionally compressed history.", "operationId": "get_working_memory_context_v1_working_memory_context__session_id__get", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "in": "query", "name": "include_compressed", "required": false, "schema": { "default": false, "title": "Include Compressed", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Working Memory Context", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/recent/{session_id}": { "get": { "description": "Get n most recent items from working memory.\n\nReturns the last n conversational turns.", "operationId": "get_recent_items_v1_working_memory_recent__session_id__get", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "in": "query", "name": "n", "required": false, "schema": { "default": 5, "maximum": 20, "minimum": 1, "title": "N", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Recent Items", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/session/{session_id}": { "delete": { "description": "Remove entire buffer for session.\n\nDeletes the buffer from manager (more thorough than clear).", "operationId": "remove_session_buffer_v1_working_memory_session__session_id__delete", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Session Buffer", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/stats": { "get": { "description": "Get statistics about all working memory buffers.\n\nReturns overall stats across all sessions.", "operationId": "get_working_memory_stats_v1_working_memory_stats_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Working Memory Stats", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 0, "x-hebbrix-operation-type": "read_operation", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } }, "/v1/working-memory/trim/{session_id}": { "post": { "description": "Trim working memory to fit within token limit.\n\nRemoves oldest items until under token limit.", "operationId": "trim_to_token_limit_v1_working_memory_trim__session_id__post", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "in": "query", "name": "max_tokens", "required": false, "schema": { "default": 4000, "maximum": 20000, "minimum": 100, "title": "Max Tokens", "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response", "headers": { "X-Idempotent-Replay": { "description": "true when this response is an exact replay of a completed request.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "401": { "description": "Authentication is missing, invalid, expired, or revoked." }, "402": { "description": "The authenticated account has insufficient operation credits. This is a billing-balance error, not an unknown operation or feature-entitlement response." }, "409": { "description": "Idempotency key conflict or an identical request is still in progress.", "headers": { "Retry-After": { "description": "Seconds before retrying an in-progress identical request.", "schema": { "minimum": 1, "type": "integer" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trim To Token Limit", "tags": [ "Working Memory", "Working Memory" ], "x-hebbrix-data-scope": { "authorization": "collection/user/agent/run scope authorized before retrieval or ranking", "classification": "explicit_tenant_scope" }, "x-hebbrix-default-credit-weight": 1, "x-hebbrix-idempotency": { "concurrent_same_key": "409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After", "fingerprint": "method + path + query + content-type + request body", "implementation": "response_replay", "same_key_different_request": "409 IDEMPOTENCY_KEY_REUSED", "same_key_same_request": "exact status/body/header replay", "scope": "authenticated actor + key", "supported": true, "ttl_seconds": 86400 }, "x-hebbrix-operation-type": "memory_raw", "x-hebbrix-plan-availability": { "minimum_plan": "route-specific", "role": "route-specific" }, "x-hebbrix-stability": "beta" } } }, "security": [ { "HTTPBearer": [] } ], "servers": [ { "description": "Hebbrix production API", "url": "https://api.hebbrix.com" } ] }