{ "openapi": "3.1.0", "servers": [ { "url": "https://platform-backend.getalchemystai.com", "description": "production" } ], "info": { "title": "Alchemyst AI API v1 documentation", "version": "1.0.0", "description": "v1 API documentation for Alchemyst AI" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid job id" }, "status": { "type": "number", "example": 400 }, "error": { "type": "object", "example": "Error details", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "User not authenticated" }, "details": { "type": "object", "additionalProperties": true } } }, "statusText": { "type": "string", "description": "Error message (detailed in debug mode)" } } }, "ContextAddAsyncStatusSuccess": { "type": "object", "required": [ "success", "jobId", "status" ], "properties": { "success": { "type": "boolean", "example": true }, "jobId": { "type": "string", "example": "job_01HXYZABC" }, "status": { "type": "string", "example": "completed" }, "result": { "type": "object", "description": "Result of the job (if available)" }, "attemptsMade": { "type": "number", "example": 1 }, "failedReason": { "type": "string", "example": "" }, "finishedOn": { "type": "number", "example": 1712345678901 }, "processedOn": { "type": "number", "example": 1712345670000 } } }, "ContextAddSuccess": { "type": "object", "required": [ "success", "context_id" ], "properties": { "success": { "type": "boolean", "example": true }, "context_id": { "type": "string", "example": "ctx_01HXYZABC" }, "processed_documents": { "type": "number", "example": 2 } } }, "MemoryUpdateSuccess": { "type": "object", "required": [ "success", "memory_id", "updated_entries" ], "properties": { "success": { "type": "boolean", "example": true }, "memory_id": { "type": "string", "example": "support-thread-TCK-1234" }, "updated_entries": { "type": "number", "example": 2 } } }, "TraceDeleteSuccess": { "type": "object", "required": [ "trace" ], "properties": { "trace": { "type": "object", "description": "The deleted trace data", "properties": { "_id": { "type": "string", "example": "trace_123" }, "userId": { "type": "string", "example": "user_123" }, "organizationId": { "type": "string", "example": "org_123" }, "type": { "type": "string", "example": "context.search" }, "data": { "type": "object", "properties": { "query": { "type": "string", "example": "What did the customer ask about pricing for the Scale plan?" }, "source": { "type": "string", "example": "support-inbox" }, "fileName": { "type": "string", "example": "support_thread_TCK-1234.txt" } } }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-10T12:35:10.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-10T12:35:10.000Z" } } } } }, "ContextViewSuccess": { "type": "object", "required": [ "success", "contexts" ], "properties": { "success": { "type": "boolean", "example": true }, "contexts": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the context item" }, "metadata": { "type": "object", "properties": { "fileName": { "type": "string" }, "fileType": { "type": "string" }, "groupName": { "type": "array", "items": { "type": "string" } }, "lastModified": { "type": "string" }, "fileSize": { "type": "number" } }, "description": "Additional metadata for the context" } } }, "description": "List of context items" } }, "example": { "success": true, "contexts": [ { "content": "Customer asked about pricing for the Scale plan.", "metadata": { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } } ] } } } }, "paths": { "/api/v1/context/add-async/{id}/cancel": { "delete": { "operationId": "cancelParticularJobInAddContextAsync", "summary": "Cancel a context add job", "description": "Attempts to cancel a context add job by job id.\n- If the job is already completed or failed, returns 404.\n- If the job is currently running (\"active\"), returns 409 and cannot be cancelled.\n- Only jobs in \"waiting\" or \"delayed\" state can be cancelled.\n", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Job ID to cancel" } ], "responses": { "200": { "description": "Job cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "jobId", "status", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "jobId": { "type": "string", "example": "job_01HXYZABC" }, "status": { "type": "string", "example": "cancelled" }, "message": { "type": "string", "example": "Job cancelled successfully" } } } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid job id" }, "status": { "type": "number", "example": 400 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" }, "status": { "type": "number", "example": 401 } } } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Payment Required" }, "status": { "type": "number", "example": 402 } } } } } }, "403": { "description": "Forbidden: insufficient scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden: insufficient scope" }, "status": { "type": "number", "example": 403 } } } } } }, "404": { "description": "Job not found or already completed/failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found" }, "status": { "type": "number", "example": 404 } } } } } }, "409": { "description": "Job is currently running and cannot be cancelled", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Context add is running, it cannot be cancelled. You can delete it after it has finished uploading, to preserve the integrity of data." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error" }, "error": { "type": "string", "example": "Error details" } } } } } } } } }, "/api/v1/context/add-async/{id}/status": { "get": { "operationId": "checkStatusForParticularJobInAddContextAsync", "summary": "Get status of a context add job", "description": "Returns the status and result of a context add job by job id.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Job ID to check status for" } ], "responses": { "200": { "description": "Job status and result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextAddAsyncStatusSuccess" } } } }, "400": { "description": "Invalid job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/add-async": { "post": { "operationId": "addContextAsync", "summary": "Asynchronously queue context data to add to the context processor", "description": "This endpoint accepts context data and queues it for asynchronous processing by the context processor. It returns a success or error response depending on the queuing result.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "context_type", "source", "scope" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the document" } }, "additionalProperties": { "type": "string" } }, "description": "Array of documents with content and additional metadata" }, "source": { "type": "string", "description": "The source of the context data" }, "context_type": { "type": "string", "enum": [ "resource", "conversation", "instruction" ], "description": "Type of context being added" }, "scope": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "Scope of the context" }, "metadata": { "type": "object", "description": "Additional metadata for the context", "properties": { "fileName": { "type": "string", "description": "Name of the file" }, "fileType": { "type": "string", "description": "Type/MIME of the file" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of Group Name to which the file belongs to" }, "lastModified": { "type": "string", "description": "Last modified timestamp" }, "fileSize": { "type": "number", "description": "Size of the file in bytes" } } }, "webhook_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional IDs of webhooks to trigger after the context is processed" } } }, "example": { "documents": [ { "content": "Customer asked about pricing for the Scale plan." } ], "source": "support-inbox", "context_type": "resource", "scope": "internal", "metadata": { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } } } } }, "responses": { "201": { "description": "Context queued successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "jobId" ], "properties": { "queued": { "type": "boolean", "example": true }, "jobId": { "type": "string", "example": "context-add-123456" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "description": "Error details" }, "status": { "type": "number", "example": 400 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found - Invalid context data format", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" } } } } } } } } }, "/api/v1/context/add-async/status": { "get": { "operationId": "checkStatusForAllAddAsyncJobs", "summary": "List all ongoing context add jobs for the authenticated user", "description": "Returns all jobs (active, waiting, delayed, failed, completed) belonging to the authenticated user.\n", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "all", "active", "failed", "completed" ], "default": "all" }, "description": "Type of jobs to list", "required": false }, { "in": "query", "name": "limit", "schema": { "type": "string", "default": "100" }, "description": "Maximum number of jobs to return", "required": false }, { "in": "query", "name": "offset", "schema": { "type": "string", "default": "0" }, "description": "Number of jobs to skip before starting to collect the result set", "required": false } ], "responses": { "200": { "description": "List of jobs", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "jobs" ], "properties": { "success": { "type": "boolean", "example": true }, "jobs": { "type": "array", "items": { "type": "object", "required": [ "jobId", "status", "attemptsMade", "data" ], "properties": { "jobId": { "type": "string", "example": "12345" }, "status": { "type": "string", "example": "active" }, "attemptsMade": { "type": "number", "example": 1 }, "failedReason": { "type": "string", "example": "Some error" }, "finishedOn": { "type": "number", "example": 1712345678901 }, "processedOn": { "type": "number", "example": 1712345678900 }, "data": { "type": "object" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": false } } } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": false } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": false } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error" }, "error": { "type": "string", "example": "Error details" } } } } } } } } }, "/api/v1/context/add": { "post": { "operationId": "addContextSync", "summary": "Add context data to the context processor", "description": "This endpoint accepts context data and sends it to a context processor for further handling. It returns a success or error response depending on the result from the context processor.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "context_type", "source", "scope" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the document" } }, "additionalProperties": { "type": "string" } }, "description": "Array of documents with content and additional metadata" }, "source": { "type": "string", "description": "The source of the context data" }, "context_type": { "type": "string", "enum": [ "resource", "conversation", "instruction" ], "description": "Type of context being added" }, "scope": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "Scope of the context" }, "metadata": { "type": "object", "description": "Additional metadata for the context", "properties": { "fileName": { "type": "string", "description": "Name of the file" }, "fileType": { "type": "string", "description": "Type/MIME of the file" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of Group Name to which the file belongs to" }, "lastModified": { "type": "string", "description": "Last modified timestamp" }, "fileSize": { "type": "number", "description": "Size of the file in bytes" } } }, "webhook_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional IDs of webhooks to trigger after the context is processed" } } }, "example": { "documents": [ { "content": "Customer asked about pricing for the Scale plan." } ], "source": "support-inbox", "context_type": "resource", "scope": "internal", "metadata": { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } } } } }, "responses": { "201": { "description": "Context added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextAddSuccess" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - Invalid context data format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/async/add": { "post": { "operationId": "addContextAsyncV2", "summary": "Asynchronously queue context data to add to the context processor", "description": "This endpoint accepts context data and queues it for asynchronous processing by the context processor. It returns a success or error response depending on the queuing result.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "context_type", "source", "scope" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the document" } }, "additionalProperties": { "type": "string" } }, "description": "Array of documents with content and additional metadata" }, "source": { "type": "string", "description": "The source of the context data" }, "context_type": { "type": "string", "enum": [ "resource", "conversation", "instruction" ], "description": "Type of context being added" }, "scope": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "Scope of the context" }, "metadata": { "type": "object", "description": "Additional metadata for the context", "properties": { "fileName": { "type": "string", "description": "Name of the file" }, "fileType": { "type": "string", "description": "Type/MIME of the file" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of Group Name to which the file belongs to" }, "lastModified": { "type": "string", "description": "Last modified timestamp" }, "fileSize": { "type": "number", "description": "Size of the file in bytes" } } }, "webhook_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional IDs of webhooks to trigger after the context is processed" } } }, "example": { "documents": [ { "content": "Customer asked about pricing for the Scale plan." } ], "source": "support-inbox", "context_type": "resource", "scope": "internal", "metadata": { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } } } } }, "responses": { "201": { "description": "Context queued successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "jobId" ], "properties": { "queued": { "type": "boolean", "example": true }, "jobId": { "type": "string", "example": "context-add-123456" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "status" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "description": "Error details" }, "status": { "type": "number", "example": 400 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found - Invalid context data format", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" } } } } } } } } }, "/api/v1/context/delete": { "post": { "operationId": "deleteContextByDocOrNodeId", "summary": "Delete context data from the context processor", "description": "This endpoint deletes context data based on the provided parameters. It returns a success or error response depending on the result from the context processor.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "organization_id" ], "properties": { "source": { "type": "string", "description": "Source identifier for the context" }, "user_id": { "type": "string", "description": "Optional user ID", "deprecated": true, "nullable": true }, "organization_id": { "type": "string", "description": "Organization ID", "nullable": false }, "by_doc": { "type": "boolean", "description": "Flag to delete by document", "default": true, "nullable": true }, "by_id": { "type": "boolean", "description": "Flag to delete by ID", "default": false, "nullable": true } } }, "example": { "source": "support-inbox", "organization_id": "org_01HXYZABC", "by_doc": true, "by_id": false } } } }, "responses": { "204": { "description": "Context deleted successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/memory/add": { "post": { "operationId": "addContextAsMemory", "summary": "Add memory context data", "description": "This endpoint adds memory (chat history) as context.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "contents" ], "properties": { "sessionId": { "type": "string", "description": "The ID of the session" }, "contents": { "type": "array", "description": "Array of content objects. Each object must contain at least the 'content' field. Additional properties are allowed.", "items": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The content of the memory message" }, "metadata": { "type": "object", "description": "Additional metadata for the message (optional)", "properties": { "messageId": { "type": "string", "description": "Unique message ID" } } } }, "additionalProperties": true } }, "metadata": { "type": "object", "description": "Optional metadata for the memory context. Defaults to [\"default\"] if not provided.", "properties": { "groupName": { "type": "array", "items": { "type": "string" }, "description": "Optional group names for the memory context. Defaults to [\"default\"] if not provided.", "default": [ "default" ] } }, "additionalProperties": true } } }, "examples": { "minimal": { "summary": "Minimal required fields only", "value": { "sessionId": "support-thread-TCK-1234", "contents": [ { "content": "Customer asked about pricing for the Scale plan." } ] } }, "withMessageMetadata": { "summary": "With message-level metadata", "value": { "sessionId": "support-thread-TCK-1234", "contents": [ { "content": "Customer asked about pricing for the Scale plan.", "metadata": { "messageId": "msg_001" } }, { "content": "Agent responded with pricing details for Scale plan.", "metadata": { "messageId": "msg_002" } } ] } }, "withGroupMetadata": { "summary": "With custom group names", "value": { "sessionId": "support-thread-TCK-1234", "contents": [ { "content": "Customer asked about pricing for the Scale plan." } ], "metadata": { "groupName": [ "support", "pricing" ] } } } } } } }, "responses": { "201": { "description": "Memory context added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextAddSuccess" }, "example": { "success": true, "context_id": "ctx_01HXYZABC", "processed_documents": 1 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "sessionId field is required" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/memory/delete": { "post": { "operationId": "deleteContextAsMemory", "summary": "Delete memory context data", "description": "Deletes memory context data based on provided parameters.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "memoryId", "organization_id" ], "properties": { "memoryId": { "type": "string", "description": "The ID of the memory to delete" }, "user_id": { "type": "string", "description": "Optional user ID", "nullable": true, "deprecated": true }, "organization_id": { "type": "string", "description": "Organization ID", "nullable": true }, "by_doc": { "type": "boolean", "description": "Delete by document flag", "default": true, "nullable": true }, "by_id": { "type": "boolean", "description": "Delete by ID flag", "default": false, "nullable": true } } }, "example": { "memoryId": "support-thread-TCK-1234", "organization_id": "org_01HXYZABC", "by_doc": true, "by_id": false } } } }, "responses": { "204": { "description": "Successfully deleted memory context" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/search": { "post": { "operationId": "searchUserContext", "summary": "Search for context data in the context processor", "description": "This endpoint sends a search request to the context processor to retrieve relevant context data based on the provided query.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "metadata", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "required": false, "description": "Controls whether metadata is included in the response:\n- metadata=true → metadata will be included in each context item in the response.\n- metadata=false (or omitted) → metadata will be excluded from the response for better performance.\n" }, { "in": "query", "name": "mode", "schema": { "type": "string", "enum": [ "fast", "standard" ], "default": "standard" }, "required": false, "description": "Controls the search mode:\n- mode=fast → prioritizes speed over completeness.\n- mode=standard → performs a comprehensive search (default if omitted).\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "similarity_threshold", "minimum_similarity_threshold" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user making the request", "example": "user123", "deprecated": true }, "query": { "type": "string", "description": "The search query used to search for context data", "example": "search query for user preferences" }, "similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Maximum similarity threshold (must be >= minimum_similarity_threshold)", "example": 0.8 }, "minimum_similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold", "example": 0.5 }, "scope": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "Search scope" }, "body_metadata": { "type": "object", "description": "Metadata filters for the search. Recognized keys: fileName,\ngroupName, lastModifiedAt, modalities. Extra keys are allowed.\nWhen body_metadata is present without groupName, the search\ndefaults to the \"default\" group.\n", "default": {}, "properties": { "fileName": { "type": "string", "description": "Filter contexts by file name", "example": "support_thread_TCK-1234.txt" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of group names to filter contexts by", "default": [ "default" ] }, "lastModifiedAt": { "type": "string", "format": "date-time", "description": "Filter contexts by last modified timestamp", "example": "2025-01-10T12:34:56.000Z" }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "description": "Modalities to search across" } }, "additionalProperties": true }, "magic_key": { "type": "string", "nullable": true, "description": "Magic key (sk_context_share_...) to search within contexts shared with the caller", "example": "sk_context_share_nC0KUEF9T6UGDHYVUiMU" }, "joined": { "type": "boolean", "default": false, "description": "When true, matching context chunks are returned joined into a single string" } } }, "examples": { "simple": { "summary": "Search without metadata filters (metadata=false or omitted)", "value": { "query": "What did the customer ask about pricing for the Scale plan?", "similarity_threshold": 0.8, "minimum_similarity_threshold": 0.5, "scope": "internal" } }, "withMetadata": { "summary": "Search with metadata filters (requires metadata=true)", "value": { "query": "What did the customer ask about pricing for the Scale plan?", "similarity_threshold": 0.8, "minimum_similarity_threshold": 0.5, "scope": "internal", "metadata": { "fileName": "support_thread_TCK-1234.txt", "groupName": [ "support", "pricing" ], "lastModifiedAt": "2025-01-10T12:34:56.000Z" }, "body_metadata": { "fileName": "support_thread_TCK-1234.txt", "groupName": [ "support", "pricing" ], "lastModifiedAt": "2025-01-10T12:34:56.000Z" } } } } } } }, "responses": { "202": { "description": "Context search request successfully processed. Response structure varies based on metadata query parameter: if metadata=true, each context includes metadata; if metadata=false or omitted, metadata is excluded from the response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contexts": { "type": "array", "items": { "type": "object", "properties": { "updatedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "description": "Only included when query parameter metadata=true" }, "content": { "type": "string" }, "score": { "type": "number", "minimum": 0.001 } } } } } } } } }, "400": { "description": "Bad Request - Invalid or missing search parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "example": "Fields missing. Detailed error: {error details}" } } } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required - User not allowed to perform action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "example": "error" } } } } } } } } }, "/api/v1/context/memory/update": { "post": { "operationId": "updateContextAsMemory", "summary": "Update memory context data", "description": "This endpoint updates memory context data.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "contents" ], "properties": { "sessionId": { "type": "string", "description": "The ID of the memory to update" }, "contents": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The content of the memory entry" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional metadata for the memory entry" }, "role": { "type": "string", "description": "Role of the message (e.g., user, assistant)" }, "id": { "type": "string", "description": "Unique ID for the message" }, "createdAt": { "type": "string", "description": "Creation timestamp" } } }, "description": "Array of updated content objects" } } }, "example": { "sessionId": "support-thread-TCK-1234", "contents": [ { "content": "Customer asked about pricing for the Scale plan.", "metadata": { "messageId": "msg-1" }, "role": "user", "id": "msg-1", "createdAt": "2025-01-10T12:34:56.000Z" }, { "content": "Updated answer about the Scale plan pricing after discounts.", "metadata": { "messageId": "msg-2" }, "role": "assistant", "id": "msg-2", "createdAt": "2025-01-10T12:36:00.000Z" } ] } } } }, "responses": { "200": { "description": "Memory context updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryUpdateSuccess" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/search/models": { "get": { "operationId": "openContextListModels", "summary": "List the models Alchemyst provides (OpenAI-compatible)", "description": "OpenAI-compatible `GET /models` endpoint.\n\nReturns only the model Alchemyst provides for this endpoint family:\n**Big Bull Alpha**, grounded with Alchemyst context retrieval.\nIt is free while in launch.\n\nPass the listing id as `model` in\n`POST /api/v1/context/search/chat/completions`, or omit `model`\nentirely — Big Bull Alpha is the default model.\n", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Models list in OpenAI format (Big Bull Alpha only).", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "Big Bull Alpha" }, "object": { "type": "string", "example": "model" }, "created": { "type": "integer", "example": 1767225600 }, "owned_by": { "type": "string", "example": "alchemyst" }, "is_free": { "type": "boolean", "example": true }, "pricing": { "type": "object", "description": "USD per token — 0 means free.", "properties": { "prompt": { "type": "string", "example": "0" }, "completion": { "type": "string", "example": "0" }, "request": { "type": "string", "example": "0" } } }, "description": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusText": { "type": "string", "example": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - User lacks required scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusText": { "type": "string", "example": "Forbidden" } } } } } } } } }, "/api/v1/context/search/steer": { "post": { "operationId": "steerUserContext", "summary": "Search context and generate an LLM-powered answer", "description": "This endpoint performs a context search using the context processor, joins all\nmatching context chunks into a single string, then sends that joined context\nalong with the user's query to an LLM to produce a\nnatural-language answer grounded in the retrieved context.\n\nBy default the response only includes the generated `answer`. Pass\n`?context=true` to also receive the joined context string that was used to\nground the answer.\n", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "mode", "schema": { "type": "string", "enum": [ "fast", "standard" ], "default": "standard" }, "required": false, "description": "Controls the search mode:\n- mode=fast -> prioritizes speed over completeness.\n- mode=standard -> performs a comprehensive search (default if omitted).\n" }, { "in": "query", "name": "context", "schema": { "type": "boolean", "default": false }, "required": false, "description": "When set to `true`, the response includes the joined `context` string used\nto ground the answer. Defaults to `false` (only `answer`,and\n`usage` are returned).\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "similarity_threshold", "minimum_similarity_threshold" ], "properties": { "user_id": { "type": "string", "description": "The ID of the user making the request", "example": "user123", "deprecated": true }, "steeringPrompt": { "type": "string", "description": "The steering prompt for the query - basically the way in which you want to get your answer as.", "example": "Return only the basic details of the person in a structured JSON schema with the fields \"name\", \"status\", \"location\"" }, "query": { "type": "string", "description": "The search query and question to be answered using retrieved context", "example": "What did the customer ask about pricing for the Scale plan?" }, "similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Maximum similarity threshold (must be >= minimum_similarity_threshold)", "example": 0.8 }, "minimum_similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold", "example": 0.5 }, "scope": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "Search scope" }, "body_metadata": { "type": "object", "description": "Metadata filters for the underlying context search. Recognized keys:\nfileName, groupName, lastModifiedAt, modalities. Extra keys are allowed.\nWhen body_metadata is present without groupName, the search\ndefaults to the \"default\" group.\n", "default": {}, "properties": { "fileName": { "type": "string", "description": "Filter contexts by file name", "example": "support_thread_TCK-1234.txt" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of group names to filter contexts by", "default": [ "default" ] }, "lastModifiedAt": { "type": "string", "format": "date-time", "description": "Filter contexts by last modified timestamp", "example": "2025-01-10T12:34:56.000Z" }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "description": "Modalities to search across" } }, "additionalProperties": true }, "magic_key": { "type": "string", "nullable": true, "description": "Magic key (sk_context_share_...) to search within contexts shared with the caller", "example": "sk_context_share_nC0KUEF9T6UGDHYVUiMU" } } }, "examples": { "simple": { "summary": "Basic steer request", "value": { "query": "What did the customer ask about pricing for the Scale plan?", "similarity_threshold": 0.8, "minimum_similarity_threshold": 0.5, "scope": "internal" } }, "withMetadata": { "summary": "Steer request with metadata filters", "value": { "query": "What did the customer ask about pricing for the Scale plan?", "similarity_threshold": 0.8, "minimum_similarity_threshold": 0.5, "scope": "internal", "body_metadata": { "fileName": "support_thread_TCK-1234.txt", "groupName": [ "support", "pricing" ], "lastModifiedAt": "2025-01-10T12:34:56.000Z" } } } } } } }, "responses": { "200": { "description": "Successfully retrieved context and generated an answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "answer", "usage" ], "properties": { "answer": { "type": "string", "description": "The LLM-generated answer based on the retrieved context" }, "context": { "type": "string", "description": "The joined context retrieved from the context processor.\nOnly present when the request was made with `?context=true`.\n" }, "usage": { "type": "object", "description": "Token usage information from the LLM", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid or missing search parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "example": "Fields missing. Detailed error: {error details}" } } } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required - User not allowed to perform action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "example": "error" } } } } } } } } }, "/api/v1/context/traces/{traceId}/delete": { "delete": { "operationId": "deleteTraceById", "summary": "Delete a specific data trace", "description": "Deletes a data trace for the authenticated user with the specified trace ID.", "tags": [ "traces" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "traceId", "required": true, "description": "The ID of the trace to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trace deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceDeleteSuccess" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/traces": { "get": { "operationId": "viewRawContextTracesForUser", "summary": "Retrieves a list of traces for the authenticated user", "description": "Returns paginated traces for the authenticated user within their organization.", "tags": [ "traces" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10 }, "description": "Number of traces per page" } ], "responses": { "200": { "description": "Successfully retrieved traces", "content": { "application/json": { "schema": { "type": "object", "required": [ "traces", "pagination" ], "properties": { "traces": { "type": "array", "items": { "type": "object", "required": [ "_id", "userId", "organizationId", "type", "data", "createdAt", "updatedAt" ], "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPrevPage" ], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPrevPage": { "type": "boolean" } } } } }, "example": { "traces": [ { "_id": "trace_123", "userId": "user_123", "organizationId": "org_123", "type": "context.search", "data": { "query": "What did the customer ask about pricing for the Scale plan?", "source": "support-inbox", "fileName": "support_thread_TCK-1234.txt" }, "createdAt": "2025-01-10T12:35:10.000Z", "updatedAt": "2025-01-10T12:35:10.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNextPage": false, "hasPrevPage": false } } } } }, "401": { "description": "Unauthorized - User or organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Unauthorized - Invalid user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/view/docs": { "get": { "operationId": "viewDocsInContextForUser", "summary": "Retrieve user contexts by documents", "description": "Fetches documents view for authenticated user with optional organization context.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "magic_key", "schema": { "type": "string" }, "required": false, "description": "Optional magic key for special access or filtering" } ], "responses": { "200": { "description": "Successfully retrieved documents view", "content": { "application/json": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "fileName", "fileType", "groupName", "lastModified", "fileSize" ], "properties": { "fileName": { "type": "string", "description": "Name of the file" }, "fileType": { "type": "string", "description": "Type/MIME of the file" }, "groupName": { "type": "array", "items": { "type": "string" }, "description": "Array of group names to which the file belongs" }, "lastModified": { "type": "string", "description": "Last modified timestamp (ISO format)" }, "fileSize": { "type": "number", "description": "Size of the file in bytes" } } } } } }, "example": { "documents": [ { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } ] } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Invalid user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/view": { "get": { "operationId": "viewRawContextNodesForUser", "summary": "Retrieve user context", "description": "Gets the context information for the authenticated user.", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "file_name", "schema": { "type": "string" }, "required": false, "description": "Name of the file to retrieve context for" }, { "in": "query", "name": "magic_key", "schema": { "type": "string" }, "required": false, "description": "Magic key for context retrieval" } ], "responses": { "200": { "description": "Successfully retrieved context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextViewSuccess" } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User doesn't have required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/context/webhook/manage/headers": { "post": { "operationId": "revealWebhookHeaders", "summary": "Reveal a webhook's custom headers", "description": "The list endpoint only reports header names. Call this when the user explicitly asks to see or copy the values, e.g. to edit them.", "tags": [ "context-webhook" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhookId" ], "properties": { "webhookId": { "type": "string" } } } } } }, "responses": { "200": { "description": "The custom headers" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Webhook not found" } } } }, "/api/v1/context/webhook/manage": { "get": { "operationId": "listWebhooks", "summary": "List registered webhooks for the organization", "tags": [ "context-webhook" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "description": "Display name for the webhook" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "hasSecret": { "type": "boolean", "description": "Whether a signing secret is set. The value is only shown once at creation and never exposed again." }, "headerNames": { "type": "array", "items": { "type": "string" }, "description": "Custom header names. Values are only available from /api/v1/context/webhook/manage/headers." }, "lastFiredAt": { "type": "string", "format": "date-time" }, "lastError": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } }, "post": { "operationId": "createWebhook", "summary": "Register a new webhook URL", "tags": [ "context-webhook" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "name": { "type": "string", "description": "Display name for the webhook" }, "url": { "type": "string", "format": "uri", "description": "The webhook endpoint URL. Must be a publicly routable http(s) address." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "context.add", "context.search", "context.steer", "context.delete", "context.view", "context.memory.add", "context.memory.delete", "context.memory.update" ] }, "description": "Events to subscribe to (defaults to all)" }, "secret": { "type": "string", "description": "Optional signing secret for HMAC verification (min 16 characters)" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "description": "Optional custom headers merged into every delivery" } } } } } }, "responses": { "201": { "description": "Webhook registered" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook's URL, event subscriptions, enabled state or signing secret", "tags": [ "context-webhook" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhookId" ], "properties": { "webhookId": { "type": "string" }, "name": { "type": "string", "description": "Display name for the webhook" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "context.add", "context.search", "context.steer", "context.delete", "context.view", "context.memory.add", "context.memory.delete", "context.memory.update" ] } }, "enabled": { "type": "boolean" }, "secret": { "type": "string", "description": "New signing secret (min 16 characters)" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Webhook updated" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Webhook not found" } } }, "delete": { "operationId": "removeWebhook", "summary": "Delete a webhook registration", "tags": [ "context-webhook" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhookId" ], "properties": { "webhookId": { "type": "string", "description": "The webhook registration ID to delete" } } } } } }, "responses": { "200": { "description": "Webhook deleted" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/api/v1/context/webhook": { "post": { "operationId": "contextWebhook", "summary": "Context processor webhook endpoint", "description": "Receives context events from the context processor and re-emits them to the SSE feed and any registered outbound webhook subscribers.", "tags": [ "context" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "organization_id" ], "properties": { "event": { "type": "string", "enum": [ "context.add", "context.async.add.started", "context.async.add.in-progress", "context.async.add.failed", "context.async.add.completed", "context.search", "context.steer", "context.delete", "context.view", "context.memory.add", "context.memory.delete", "context.memory.update" ] }, "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Event received" }, "400": { "description": "Bad request - invalid payload" }, "401": { "description": "Invalid webhook secret" }, "500": { "description": "Internal server error" } } } }, "/api/v1/org/context/view/docs": { "post": { "operationId": "viewOrgDocs", "summary": "Retrieve organization contexts by documents", "description": "Fetches documents view for an organization with role-based visibility.", "tags": [ "Organization" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userIds" ], "properties": { "userIds": { "type": "array", "items": { "type": "string" }, "description": "Array of user IDs to fetch documents for" } } } } } }, "responses": { "200": { "description": "Successfully retrieved documents view", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "id": { "type": "string" }, "doc_type": { "type": "string" }, "group_name": { "type": "array", "items": { "type": "string" } }, "size": { "type": "number" }, "last_modified_at": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - User not authenticated" }, "402": { "description": "Invalid user" }, "403": { "description": "Forbidden - User lacks required scope" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/org/context/view": { "post": { "operationId": "viewOrgContext", "tags": [ "Organization" ], "summary": "View organization context", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userIds" ], "properties": { "userIds": { "type": "array", "items": { "type": "string" }, "deprecated": true } } }, "example": { "userIds": [ "user_123", "user_456" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contexts": { "type": "object" } } }, "example": { "contexts": { "user_123": [ { "content": "Customer asked about pricing for the Scale plan.", "metadata": { "fileName": "support_thread_TCK-1234.txt", "fileType": "text/plain", "groupName": [ "support", "pricing" ], "lastModified": "2025-01-10T12:34:56.000Z", "fileSize": 2048 } } ] } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Invalid user" }, "403": { "description": "Forbidden" }, "500": { "description": "Context processor error" } } } }, "/api/v1/org/members/role": { "patch": { "operationId": "updateOrgMemberRole", "summary": "Update a member's role in an organization", "description": "Updates the role of a specific member within an organization. The user performing this action must be the 'owner' of the organization. The target member's role cannot be 'owner'.\n", "tags": [ "Organization Members" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The ID of the organization.", "example": "60d0fe4f5311236168a109ca" }, "memberId": { "type": "string", "description": "The user ID of the member whose role is to be updated.", "example": "60d0fe4f5311236168a109cb" }, "role": { "type": "string", "description": "The new role for the member.", "enum": [ "member", "admin" ], "example": "admin" } }, "required": [ "organizationId", "memberId", "role" ] } } } }, "responses": { "200": { "description": "Role updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Role updated successfully" }, "member": { "type": "object", "properties": { "userId": { "type": "string", "example": "60d0fe4f5311236168a109cb" }, "role": { "type": "string", "example": "admin" } } } } } } } }, "400": { "description": "Bad Request - Missing required fields, invalid role, or invalid ID format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing required fields: organizationId, memberId, role" } } } } } }, "401": { "description": "Unauthorized - User is not authenticated." }, "402": { "description": "Payment Required - User's subscription is not valid." }, "403": { "description": "Forbidden - User does not have 'owner' role, or is trying to change the role of an owner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Insufficient permissions - owner role required" } } } } } }, "404": { "description": "Not Found - The target member was not found in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Member not found in organization" } } } } } }, "500": { "description": "Internal Server Error." } } } } }, "tags": [] }