{"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"}}}}},"example":{"documents":[{"content":"Customer asked about pricing for the Scale plan.","containerTag":"support-emails","ticketId":"TCK-1234"}],"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"}}}}},"example":{"documents":[{"content":"Customer asked about pricing for the Scale plan.","containerTag":"support-emails","ticketId":"TCK-1234"}],"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/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/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":{"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":"Additional metadata for the search","default":{}}}},"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"}}}}}}},"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/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/org/context/view":{"post":{"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"}}}}},"tags":[]}