{ "openapi": "3.1.0", "info": { "title": "GraphRAG API", "description": "Knowledge Graph query agents for protein-disease relationships. Supports multiple LLM backends, graph + vector hybrid search, and SSE streaming.", "version": "0.1.0" }, "paths": { "/v1/ingestion/jobs": { "post": { "tags": [ "ingestion" ], "summary": "Create Job", "description": "Create a new ingestion job and start background execution.\n\nAccepts both JSON (for pubmed/biorxiv) and multipart/form-data (for pdf with files).\n\nReturns:\n JobResponse with job_id and initial status\n\nRaises:\n HTTPException 400: Invalid request parameters or missing files for PDF source\n HTTPException 503: Redis not available", "operationId": "create_job_v1_ingestion_jobs_post", "security": [ { "HTTPBearer": [] } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } } } }, "get": { "tags": [ "ingestion" ], "summary": "List Jobs", "description": "List recent ingestion jobs.\n\nArgs:\n days: Number of days to look back (default: 7)\n\nReturns:\n List of JobResponse objects sorted by creation time (newest first)", "operationId": "list_jobs_v1_ingestion_jobs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobResponse" }, "title": "Response List Jobs V1 Ingestion Jobs Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}": { "get": { "tags": [ "ingestion" ], "summary": "Get Job Status", "description": "Get the status and progress of an ingestion job.\n\nArgs:\n job_id: Unique job identifier\n\nReturns:\n JobResponse with current status and progress\n\nRaises:\n HTTPException 404: Job not found", "operationId": "get_job_status_v1_ingestion_jobs__job_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "ingestion" ], "summary": "Cancel Job", "description": "Cancel a running or pending ingestion job.\n\nArgs:\n job_id: Unique job identifier\n\nReturns:\n JobResponse with updated status\n\nRaises:\n HTTPException 404: Job not found", "operationId": "cancel_job_v1_ingestion_jobs__job_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}/permanent": { "delete": { "tags": [ "ingestion" ], "summary": "Delete Job", "description": "Permanently delete a completed, failed, or cancelled job from Redis.\n\nReturns:\n Success message or 404/400 error", "operationId": "delete_job_v1_ingestion_jobs__job_id__permanent_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/db-stats": { "get": { "tags": [ "ingestion" ], "summary": "Get Db Stats", "description": "Get overall database statistics (cached 24h, pass refresh=true to force).\n\nArgs:\n database: Database identifier to query stats for\n refresh: Force refresh the cache\n\nReturns:\n Dict with total_nodes, total_relationships, label_counts, schema, degree_stats", "operationId": "get_db_stats_v1_ingestion_db_stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "database", "in": "query", "required": false, "schema": { "type": "string", "default": "olink3", "title": "Database" } }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Refresh" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/stats": { "get": { "tags": [ "ingestion" ], "summary": "Get Ingestion Stats", "description": "Get aggregated ingestion performance statistics.\n\nAggregates metrics from completed jobs within the time window.\n\nArgs:\n days: Number of days to look back (default: 7)\n\nReturns:\n Aggregated stats: total jobs, tokens, time, entity counts", "operationId": "get_ingestion_stats_v1_ingestion_stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}/subgraph": { "get": { "tags": [ "ingestion" ], "summary": "Get Job Subgraph", "description": "Return all nodes and edges for a given ingestion job.\n\nChecks Redis first; falls back to Neo4j when cache is expired or unavailable.\n\nArgs:\n job_id: Unique job identifier\n\nReturns:\n JSON with job_id, node_count, edge_count, nodes, edges, source, created_at\n\nRaises:\n HTTPException 404: Job not found in Redis or Neo4j", "operationId": "get_job_subgraph_v1_ingestion_jobs__job_id__subgraph_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "ingestion" ], "summary": "Delete Job Subgraph", "description": "Delete all nodes and relationships created by a specific ingestion job.\n\nRemoves the sub-graph tagged with *ingestion_job_id* from Neo4j and\nclears the corresponding Redis cache keys.\n\nReturns:\n JSON with job_id, removed_nodes, removed_relationships", "operationId": "delete_job_subgraph_v1_ingestion_jobs__job_id__subgraph_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}/summary": { "get": { "tags": [ "ingestion" ], "summary": "Get Job Summary", "description": "Return a summary of the ingested documents for a completed job.", "operationId": "get_job_summary_v1_ingestion_jobs__job_id__summary_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}/query": { "post": { "tags": [ "ingestion" ], "summary": "Query Job", "description": "Answer a question about the documents ingested by a specific job.", "operationId": "query_job_v1_ingestion_jobs__job_id__query_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/jobs/{job_id}/retry": { "post": { "tags": [ "ingestion" ], "summary": "Retry Job", "description": "Retry a failed or cancelled job by creating a new job with the same parameters.\n\nReturns:\n JobResponse for the newly created job", "operationId": "retry_job_v1_ingestion_jobs__job_id__retry_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/dlq": { "get": { "tags": [ "ingestion-dlq" ], "summary": "List Dlq Messages", "description": "List DLQ messages with optional filtering.\n\nAdmin-only endpoint (enforced by RBAC middleware).\n\nArgs:\n error_type: Optional filter by error type\n (e.g. timeout, connection_error, validation_error).\n start_date: Optional ISO 8601 start date for date range filter.\n end_date: Optional ISO 8601 end date for date range filter.\n\nReturns:\n DLQListResponse with matching messages and count.", "operationId": "list_dlq_messages_v1_ingestion_dlq_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "error_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by error type category", "title": "Error Type" }, "description": "Filter by error type category" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter start date (ISO 8601)", "title": "Start Date" }, "description": "Filter start date (ISO 8601)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter end date (ISO 8601)", "title": "End Date" }, "description": "Filter end date (ISO 8601)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DLQListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ingestion/dlq/{message_id}/retry": { "post": { "tags": [ "ingestion-dlq" ], "summary": "Retry Dlq Message", "description": "Re-enqueue a DLQ message for reprocessing.\n\nAdmin-only endpoint (enforced by RBAC middleware).\n\nFinds the message in the DLQ by ID, sends it back to the main\ningestion queue, and removes it from the DLQ.\n\nArgs:\n message_id: The SQS message ID to retry.\n\nReturns:\n DLQRetryResponse indicating success or failure.", "operationId": "retry_dlq_message_v1_ingestion_dlq__message_id__retry_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DLQRetryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sessions": { "post": { "tags": [ "sessions" ], "summary": "Create Session", "description": "Create a new query session.\n\nInitializes a session with the specified configuration including LLM service,\ndatabase connection, and agent type. Returns a session ID for subsequent queries.\n\nArgs:\n payload: Session configuration including llm_service, database_name,\n database_type, agent_type, and optional settings\n\nReturns:\n SessionCreateResponse with session_id, created_at, and config", "operationId": "create_session_v1_sessions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/sessions/{session_id}": { "get": { "tags": [ "sessions" ], "summary": "Get Session", "description": "Get session details and query history.\n\nReturns the session configuration and a list of all queries executed\nin the session with their results.\n\nArgs:\n session_id: The session ID to retrieve\n\nReturns:\n SessionSummaryResponse with session details and history", "operationId": "get_session_v1_sessions__session_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "sessions" ], "summary": "Delete Session", "description": "Delete a session and release its resources.\n\nCloses the session and cleans up any associated resources.\nThis operation is idempotent - deleting a non-existent session\nreturns success (204).\n\nArgs:\n session_id: The session ID to delete\n\nReturns:\n HTTP 204 No Content on success", "operationId": "delete_session_v1_sessions__session_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sessions/{session_id}/query": { "post": { "tags": [ "query" ], "summary": "Execute Query", "description": "Execute a query against a session.\n\nSupports two response modes:\n- Standard JSON response (stream=false, default)\n- Server-Sent Events streaming (stream=true)\n\nArgs:\n session_id: The session ID to query against\n payload: Query parameters including question, mode, and streaming options\n\nReturns:\n QueryResponse for JSON mode, or StreamingResponse for SSE mode", "operationId": "execute_query_v1_sessions__session_id__query_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sessions/{session_id}/expand-knn": { "post": { "tags": [ "expansion" ], "summary": "Expand Knn", "description": "Expand query results with k-nearest neighbors from the database.\n\nThis endpoint performs network expansion equivalent to the Streamlit UI's\n\"Expand Network\" button. It finds additional entities connected to your\ncurrent results and returns expanded nodes and links.\n\nThe expansion uses cached results from the most recent query (or specified query_index)\nin the session, eliminating the need to resend data from the frontend.\n\nRequirements:\n- Session must use Neo4j database\n- Session agent must support KNN expansion\n- Session must have at least one previous query with results to expand\n\nThe expansion returns:\n- expanded_results: Dict with 'nodes' and 'links' arrays\n- new_neighbors_count: Number of new nodes added\n- expansion_level: Level of expansion performed\n- entity_types_added: Count by entity type", "operationId": "expand_knn_v1_sessions__session_id__expand_knn_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KNNExpansionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KNNExpansionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sessions/{session_id}/stats": { "get": { "tags": [ "expansion" ], "summary": "Get Database Stats", "description": "Get database statistics including node counts, link counts, and degree distribution.\n\nReturns comprehensive statistics about the database connected to the session.", "operationId": "get_database_stats_v1_sessions__session_id__stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/evidence": { "get": { "tags": [ "evidence" ], "summary": "Get Evidence", "description": "Return the source sentence and chunk context for a given chunk and char offsets.\n\nArgs:\n chunk_id: The chunk identifier to look up.\n char_start: Start character offset of the sentence within the chunk text.\n char_end: End character offset of the sentence within the chunk text.\n\nReturns:\n JSON with sentence, chunk_id, chunk_text, char_start, char_end, pmid, abstract_title.\n\nRaises:\n HTTPException 404: Chunk not found.", "operationId": "get_evidence_v1_evidence_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "chunk_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Chunk Id" } }, { "name": "char_start", "in": "query", "required": true, "schema": { "type": "integer", "title": "Char Start" } }, { "name": "char_end", "in": "query", "required": true, "schema": { "type": "integer", "title": "Char End" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/communities/temporal": { "get": { "tags": [ "communities" ], "summary": "Get Temporal Communities", "description": "Detect communities within a temporal slice of the knowledge graph.\n\nReturns the list of TemporalCommunities detected within the specified\ntime window. Returns 400 if start_time > end_time.", "operationId": "get_temporal_communities_v1_communities_temporal_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "start_time", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of time range (ISO 8601 UTC)", "title": "Start Time" }, "description": "Start of time range (ISO 8601 UTC)" }, { "name": "end_time", "in": "query", "required": true, "schema": { "type": "string", "description": "End of time range (ISO 8601 UTC)", "title": "End Time" }, "description": "End of time range (ISO 8601 UTC)" }, { "name": "min_community_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Minimum community size", "default": 3, "title": "Min Community Size" }, "description": "Minimum community size" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCommunity" }, "title": "Response Get Temporal Communities V1 Communities Temporal Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/communities/evolution": { "get": { "tags": [ "communities" ], "summary": "Get Community Evolution", "description": "Track community evolution across consecutive time windows.\n\nReturns an ordered sequence of CommunityEvolutionRecords.\nReturns 400 if start_time > end_time or snapshot limit exceeded.", "operationId": "get_community_evolution_v1_communities_evolution_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "start_time", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of time range (ISO 8601 UTC)", "title": "Start Time" }, "description": "Start of time range (ISO 8601 UTC)" }, { "name": "end_time", "in": "query", "required": true, "schema": { "type": "string", "description": "End of time range (ISO 8601 UTC)", "title": "End Time" }, "description": "End of time range (ISO 8601 UTC)" }, { "name": "step_interval", "in": "query", "required": true, "schema": { "type": "integer", "description": "Step interval in seconds between snapshots", "title": "Step Interval" }, "description": "Step interval in seconds between snapshots" }, { "name": "similarity_threshold", "in": "query", "required": false, "schema": { "type": "number", "maximum": 1.0, "minimum": 0.0, "description": "Jaccard similarity threshold for linking communities", "default": 0.5, "title": "Similarity Threshold" }, "description": "Jaccard similarity threshold for linking communities" }, { "name": "min_community_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Minimum community size", "default": 3, "title": "Min Community Size" }, "description": "Minimum community size" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommunityEvolutionRecord" }, "title": "Response Get Community Evolution V1 Communities Evolution Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/communities/team/{team_name}": { "get": { "tags": [ "communities" ], "summary": "Get Team Communities", "description": "Detect communities within a team's contributed subgraph.\n\nReturns the list of TeamScopedCommunities for the specified team.\nReturns 400 if start_time > end_time when both are provided.", "operationId": "get_team_communities_v1_communities_team__team_name__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Team Name" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional start of time range (ISO 8601 UTC)", "title": "Start Time" }, "description": "Optional start of time range (ISO 8601 UTC)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional end of time range (ISO 8601 UTC)", "title": "End Time" }, "description": "Optional end of time range (ISO 8601 UTC)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamScopedCommunity" }, "title": "Response Get Team Communities V1 Communities Team Team Name Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/communities/team-comparison": { "get": { "tags": [ "communities" ], "summary": "Compare Teams", "description": "Compare community structures between two teams.\n\nReturns a TeamComparisonResult with communities for both teams,\nshared entities, and overlapping communities.\nReturns 400 if start_time > end_time when both are provided.", "operationId": "compare_teams_v1_communities_team_comparison_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team_a", "in": "query", "required": true, "schema": { "type": "string", "description": "Name of the first team", "title": "Team A" }, "description": "Name of the first team" }, { "name": "team_b", "in": "query", "required": true, "schema": { "type": "string", "description": "Name of the second team", "title": "Team B" }, "description": "Name of the second team" }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional start of time range (ISO 8601 UTC)", "title": "Start Time" }, "description": "Optional start of time range (ISO 8601 UTC)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional end of time range (ISO 8601 UTC)", "title": "End Time" }, "description": "Optional end of time range (ISO 8601 UTC)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamComparisonResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells": { "post": { "tags": [ "cells" ], "summary": "Create Cell", "description": "Create a new cell in a thread and kick off query execution in the background.", "operationId": "create_cell_v1_threads__thread_id__cells_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCellRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "cells" ], "summary": "Get Tree", "description": "Get the full cell tree for a thread.", "operationId": "get_tree_v1_threads__thread_id__cells_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellTreeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}": { "get": { "tags": [ "cells" ], "summary": "Get Cell", "description": "Get a single cell, optionally with conversation context.", "operationId": "get_cell_v1_threads__thread_id__cells__cell_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } }, { "name": "include_context", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Context" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CellResponse" }, { "$ref": "#/components/schemas/CellWithContextResponse" } ], "title": "Response Get Cell V1 Threads Thread Id Cells Cell Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "cells" ], "summary": "Delete Cell", "description": "Delete a cell and all its descendants from the tree.", "operationId": "delete_cell_v1_threads__thread_id__cells__cell_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Cell V1 Threads Thread Id Cells Cell Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/branch": { "post": { "tags": [ "cells" ], "summary": "Branch Cell", "description": "Branch from an existing cell with a new query.", "operationId": "branch_cell_v1_threads__thread_id__cells__cell_id__branch_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCellRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/retry": { "post": { "tags": [ "cells" ], "summary": "Retry Cell", "description": "Re-run a cell's query by resetting it to pending and re-executing.", "operationId": "retry_cell_v1_threads__thread_id__cells__cell_id__retry_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryCellRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/dag": { "get": { "tags": [ "cells" ], "summary": "Get Dag", "description": "Get the execution DAG for a thread.", "operationId": "get_dag_v1_threads__thread_id__dag_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DAGResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/outputs": { "get": { "tags": [ "cells" ], "summary": "Get Cell Outputs", "description": "Get the output elements for a specific cell.", "operationId": "get_cell_outputs_v1_threads__thread_id__cells__cell_id__outputs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/execute": { "post": { "tags": [ "cells" ], "summary": "Execute Cells", "description": "Execute multiple cells in DAG-resolved order.", "operationId": "execute_cells_v1_threads__thread_id__execute_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/expand-knn": { "post": { "tags": [ "cells" ], "summary": "Cell Expand Knn", "description": "Expand a cell's network graph via APOC/Cypher neighbor traversal.", "operationId": "cell_expand_knn_v1_threads__thread_id__cells__cell_id__expand_knn_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellExpandKNNRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellExpandKNNResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/expand-knn-cell": { "post": { "tags": [ "cells" ], "summary": "Expand Knn Cell", "description": "Expand a cell's network via KNN and create a child cell with structured outputs.", "operationId": "expand_knn_cell_v1_threads__thread_id__cells__cell_id__expand_knn_cell_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpandKNNCellRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/detect-communities": { "post": { "tags": [ "cells" ], "summary": "Detect Communities", "description": "Run community detection on a cell's network and create a child cell.", "operationId": "detect_communities_v1_threads__thread_id__cells__cell_id__detect_communities_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectCommunitiesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/cells/{cell_id}/analyze-centrality": { "post": { "tags": [ "cells" ], "summary": "Analyze Centrality", "description": "Run centrality analysis on a cell's network and create a child cell.", "operationId": "analyze_centrality_v1_threads__thread_id__cells__cell_id__analyze_centrality_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } }, { "name": "cell_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Cell Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeCentralityRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/org/{org_id}/threads": { "get": { "tags": [ "cells" ], "summary": "List Org Threads", "description": "List all threads belonging to an organization.", "operationId": "list_org_threads_v1_org__org_id__threads_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgThreadSummary" }, "title": "Response List Org Threads V1 Org Org Id Threads Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads/{thread_id}/permission": { "patch": { "tags": [ "cells" ], "summary": "Update Thread Permission", "description": "Update the permission level of a thread. Only the owner can do this.", "operationId": "update_thread_permission_v1_threads__thread_id__permission_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePermissionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/threads": { "post": { "tags": [ "cells" ], "summary": "Create Thread", "description": "Create a new thread with optional org association.", "operationId": "create_thread_v1_threads_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateThreadRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/threads/{thread_id}/share": { "patch": { "tags": [ "cells" ], "summary": "Share Thread To Org", "description": "Share an existing thread to an organization.\n\nSets org_id and owner_id on the thread, adds it to the org index,\nand sets the permission level for org members.", "operationId": "share_thread_to_org_v1_threads__thread_id__share_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Thread Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareToOrgRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/upload": { "post": { "tags": [ "my-files" ], "summary": "Upload File", "description": "Upload a CSV or Excel file.", "operationId": "upload_file_v1_my_files_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_file_v1_my_files_upload_post" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/my-files/stats": { "get": { "tags": [ "my-files" ], "summary": "Get My Files Stats", "description": "Return aggregate stats for the Data Analysis workspace.\n\nIncludes file counts, total size, type breakdown, and lineage edge count.", "operationId": "get_my_files_stats_v1_my_files_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get My Files Stats V1 My Files Stats Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/my-files/{file_id}/schema": { "get": { "tags": [ "my-files" ], "summary": "Get Schema", "description": "Return inferred column schema and stats for a file.", "operationId": "get_schema_v1_my_files__file_id__schema_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetSchema" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/preview": { "get": { "tags": [ "my-files" ], "summary": "Get Preview", "description": "Return paginated preview rows.", "operationId": "get_preview_v1_my_files__file_id__preview_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/rename-column": { "post": { "tags": [ "my-files" ], "summary": "Rename Column", "description": "Rename a column in the uploaded file (modifies the server-side file).", "operationId": "rename_column_v1_my_files__file_id__rename_column_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameColumnRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/generate-code": { "post": { "tags": [ "my-files" ], "summary": "Generate Code", "description": "Generate Python code from a natural-language query.", "operationId": "generate_code_v1_my_files__file_id__generate_code_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCodeRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/suggestions": { "get": { "tags": [ "my-files" ], "summary": "Get Suggestions", "description": "Return LLM-generated exploration suggestions.", "operationId": "get_suggestions_v1_my_files__file_id__suggestions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/describe": { "post": { "tags": [ "my-files" ], "summary": "Describe Dataset", "description": "Parse user-provided free-text context into structured metadata.\n\nThe user writes about where the dataset comes from, what columns mean,\nand how entities relate in their domain. The LLM extracts structured\nannotations (entities, relationships, column mappings) for the KG.\n\nRole resolution order:\n1. ``body.role`` (explicit from the form)\n2. ``X-User-Role`` header (set by SSO/Microsoft Entra proxy)\n3. ``None`` (omitted from the prompt)", "operationId": "describe_dataset_v1_my_files__file_id__describe_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeDatasetRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/export-to-kg": { "post": { "tags": [ "my-files" ], "summary": "Export To Kg", "description": "Extract entities/relationships from the file and store in Neo4j.", "operationId": "export_to_kg_v1_my_files__file_id__export_to_kg_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/ingest": { "post": { "tags": [ "my-files" ], "summary": "Ingest File", "description": "Send a tabular file through the full KG ingestion pipeline.", "operationId": "ingest_file_v1_my_files__file_id__ingest_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IngestRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/extract-metadata": { "post": { "tags": [ "my-files" ], "summary": "Extract Metadata", "description": "Run MetadataExtractor on the file and return extracted hints.", "operationId": "extract_metadata_v1_my_files__file_id__extract_metadata_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractedMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/metadata": { "post": { "tags": [ "my-files" ], "summary": "Save Metadata", "description": "Save initial metadata for a file.", "operationId": "save_metadata_v1_my_files__file_id__metadata_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadataInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "my-files" ], "summary": "Get Metadata", "description": "Get metadata for a file.", "operationId": "get_metadata_v1_my_files__file_id__metadata_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "my-files" ], "summary": "Update Metadata", "description": "Update metadata for a file.", "operationId": "update_metadata_v1_my_files__file_id__metadata_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadataInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/lineage/tree": { "get": { "tags": [ "my-files" ], "summary": "Get Lineage Tree", "description": "Get the full lineage tree for a session.", "operationId": "get_lineage_tree_v1_my_files_lineage_tree_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineageTree" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/lineage/edges": { "post": { "tags": [ "my-files" ], "summary": "Add Lineage Edge", "description": "Add a lineage edge. The file_id is the context file.\n\nIf parent_id is provided, creates edge parent_id \u2192 file_id.\nIf child_id is provided, creates edge file_id \u2192 child_id.", "operationId": "add_lineage_edge_v1_my_files__file_id__lineage_edges_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineageEdgeRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineageEdge" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/my-files/{file_id}/lineage/edges/{edge_id}": { "delete": { "tags": [ "my-files" ], "summary": "Remove Lineage Edge", "description": "Remove a lineage edge.", "operationId": "remove_lineage_edge_v1_my_files__file_id__lineage_edges__edge_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "edge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Edge Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/auto-discovery/candidates": { "get": { "tags": [ "auto-discovery" ], "summary": "List Candidates", "description": "List pending candidate statistical edges with cursor-based pagination.", "operationId": "list_candidates_v1_auto_discovery_candidates_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Number of candidates per page", "default": 20, "title": "Page Size" }, "description": "Number of candidates per page" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination (candidate_id)", "title": "Cursor" }, "description": "Cursor for pagination (candidate_id)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateListResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/auto-discovery/candidates/{candidate_id}/confirm": { "post": { "tags": [ "auto-discovery" ], "summary": "Confirm Candidate", "description": "Confirm a candidate statistical edge, promoting it to a full Statistical_Edge.", "operationId": "confirm_candidate_v1_auto_discovery_candidates__candidate_id__confirm_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Confirm Candidate V1 Auto Discovery Candidates Candidate Id Confirm Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/auto-discovery/candidates/{candidate_id}/reject": { "post": { "tags": [ "auto-discovery" ], "summary": "Reject Candidate", "description": "Reject a candidate statistical edge.", "operationId": "reject_candidate_v1_auto_discovery_candidates__candidate_id__reject_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Reject Candidate V1 Auto Discovery Candidates Candidate Id Reject Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/auto-discovery/scan": { "post": { "tags": [ "auto-discovery" ], "summary": "Scan Dataset", "description": "Trigger an auto-discovery scan on a dataset.\n\nNote: this is a simplified endpoint \u2014 in production the DataFrame\nwould come from the ingestion pipeline.", "operationId": "scan_dataset_v1_auto_discovery_scan_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Scan Dataset V1 Auto Discovery Scan Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/documents/{file_id}/mappings/suggest": { "get": { "tags": [ "document-graph" ], "summary": "Suggest Mappings", "description": "Get column mapping suggestions for a document.\n\nReturns ranked entity match candidates for each column in the document.", "operationId": "suggest_mappings_v1_documents__file_id__mappings_suggest_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnMappingSuggestion" }, "title": "Response Suggest Mappings V1 Documents File Id Mappings Suggest Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/mappings/confirm": { "post": { "tags": [ "document-graph" ], "summary": "Confirm Mapping", "description": "Confirm a column-to-entity mapping.\n\nPersists the mapping as a MAPS_COLUMN relationship in Neo4j with provenance.", "operationId": "confirm_mapping_v1_documents__file_id__mappings_confirm_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmMappingRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmedMapping" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/mappings/reject": { "post": { "tags": [ "document-graph" ], "summary": "Reject Mapping", "description": "Reject a mapping suggestion.\n\nRecords the rejection so the entity is excluded from future suggestions\nfor this column in the current session.", "operationId": "reject_mapping_v1_documents__file_id__mappings_reject_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectMappingRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/connectivity": { "get": { "tags": [ "document-graph" ], "summary": "Get Connectivity", "description": "Get document-graph connectivity.\n\nReturns all entities linked to the document through confirmed mappings,\nstatistical edges, annotations, and ingestion relationships.", "operationId": "get_connectivity_v1_documents__file_id__connectivity_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Entities per page", "default": 20, "title": "Page Size" }, "description": "Entities per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentConnectivity" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/connectivity/{entity_id}/neighborhood": { "get": { "tags": [ "document-graph" ], "summary": "Get Entity Neighborhood", "description": "Get entity neighborhood subgraph.\n\nReturns the N-hop subgraph around the specified entity.", "operationId": "get_entity_neighborhood_v1_documents__file_id__connectivity__entity_id__neighborhood_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } }, { "name": "hops", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 3, "minimum": 1, "description": "Number of hops", "default": 1, "title": "Hops" }, "description": "Number of hops" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphNeighborhood" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/explore": { "get": { "tags": [ "document-graph" ], "summary": "Get Exploration Suggestions", "description": "Get graph-guided exploration suggestions for a document.\n\nCombines the document's schema with graph connectivity to generate\ncontextual exploration suggestions.", "operationId": "get_exploration_suggestions_v1_documents__file_id__explore_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GraphExplorationSuggestion" }, "title": "Response Get Exploration Suggestions V1 Documents File Id Explore Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/explore/execute": { "post": { "tags": [ "document-graph" ], "summary": "Execute Exploration", "description": "Create a code cell from an exploration suggestion.\n\nGenerates an executable code cell in the notebook system with the\nsuggestion's analysis code.", "operationId": "execute_exploration_v1_documents__file_id__explore_execute_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteExplorationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/annotations": { "post": { "tags": [ "document-graph" ], "summary": "Create Annotations", "description": "Create one or more annotations for a document.\n\nEach annotation links a document column to a graph entity with an\noptional free-text note.", "operationId": "create_annotations_v1_documents__file_id__annotations_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationsRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" }, "title": "Response Create Annotations V1 Documents File Id Annotations Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "document-graph" ], "summary": "List Annotations", "description": "List all annotations for a document grouped by column.\n\nReturns a dictionary mapping column names to their annotations.", "operationId": "list_annotations_v1_documents__file_id__annotations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/annotations/{annotation_id}": { "delete": { "tags": [ "document-graph" ], "summary": "Delete Annotation", "description": "Delete an annotation.\n\nRemoves the annotation and updates the document's graph connectivity.", "operationId": "delete_annotation_v1_documents__file_id__annotations__annotation_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } }, { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Identifier of the user deleting the annotation", "title": "User Id" }, "description": "Identifier of the user deleting the annotation" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/enrich": { "post": { "tags": [ "document-graph" ], "summary": "Start Enrichment", "description": "Start an enrichment workflow for a document.\n\nExecutes the enrichment pipeline as a background task: schema analysis,\ncolumn mapping, auto-discovery scan, and graph-guided exploration.", "operationId": "start_enrichment_v1_documents__file_id__enrich_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/enrich/{workflow_id}/progress": { "get": { "tags": [ "document-graph" ], "summary": "Get Enrichment Progress", "description": "Get progress of a running enrichment workflow.\n\nReturns the current status of each workflow step.", "operationId": "get_enrichment_progress_v1_documents__file_id__enrich__workflow_id__progress_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowProgress" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/{file_id}/provenance": { "get": { "tags": [ "document-graph" ], "summary": "Get Provenance", "description": "Get provenance history for a document.\n\nReturns a chronological list of all graph interactions for the document,\nwith optional filtering by action type, actor, and date range.", "operationId": "get_provenance_v1_documents__file_id__provenance_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "action_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by action type", "title": "Action Type" }, "description": "Filter by action type" }, { "name": "actor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by actor", "title": "Actor" }, "description": "Filter by actor" }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start of date range", "title": "Date From" }, "description": "Start of date range" }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of date range", "title": "Date To" }, "description": "End of date range" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProvenanceEvent" }, "title": "Response Get Provenance V1 Documents File Id Provenance Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/search/entities": { "get": { "tags": [ "document-graph" ], "summary": "Search Entities", "description": "Search graph entities from the document workspace.\n\nReturns matching entities ranked by relevance, with indicators for\nentities already connected to the specified document.", "operationId": "search_entities_v1_documents_search_entities_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Text search query", "title": "Query" }, "description": "Text search query" }, { "name": "file_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional document ID for proximity boosting", "title": "File Id" }, "description": "Optional document ID for proximity boosting" }, { "name": "entity_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by entity type", "title": "Entity Type" }, "description": "Filter by entity type" }, { "name": "min_confidence", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "description": "Minimum confidence threshold", "title": "Min Confidence" }, "description": "Minimum confidence threshold" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum results", "default": 20, "title": "Limit" }, "description": "Maximum results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySearchResult" }, "title": "Response Search Entities V1 Documents Search Entities Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/documents/overlay": { "post": { "tags": [ "document-graph" ], "summary": "Compute Overlay", "description": "Compute a multi-document graph overlay.\n\nReturns shared entities and edges across the selected documents,\nwith overlap counts and contributing document lists.", "operationId": "compute_overlay_v1_documents_overlay_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverlayRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiDocumentOverlay" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/healthz": { "get": { "tags": [ "health" ], "summary": "Healthcheck", "description": "Legacy health check endpoint with Redis status.\n\nReturns overall status and component health.", "operationId": "healthcheck_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Health", "description": "Aggregate health status with individual dependency details.\n\nReturns HTTP 503 if any critical dependency (database, aurora, bedrock)\nis unhealthy. Otherwise returns HTTP 200 with the full health report.\nIncludes estimated_recovery_seconds from circuit breaker state.", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health/ready": { "get": { "tags": [ "health" ], "summary": "Health Ready", "description": "Readiness probe \u2014 returns 200 only when ALL dependencies are healthy.\n\nUsed by ECS deployment checks to determine if the service is ready\nto accept traffic.", "operationId": "health_ready_health_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health/live": { "get": { "tags": [ "health" ], "summary": "Health Live", "description": "Liveness probe \u2014 always returns HTTP 200 if the process is running.\n\nUsed by container health checks. Independent of dependency state.", "operationId": "health_live_health_live_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/metrics": { "get": { "tags": [ "metrics" ], "summary": "Get Metrics Dashboard", "description": "Return comprehensive metrics dashboard.\n\nIncludes:\n- Multi-hop query success rate\n- Community summary usage percentage\n- Query mode classification accuracy\n- Entity disambiguation recall\n- Cache hit rate\n- Query latency percentiles (P50, P95, P99)\n- Incremental update metrics\n\nRequires authentication.", "operationId": "get_metrics_dashboard_v1_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Metrics Dashboard V1 Metrics Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/multi-hop": { "get": { "tags": [ "metrics" ], "summary": "Get Multi Hop Metrics", "description": "Return multi-hop query success rate metrics.", "operationId": "get_multi_hop_metrics_v1_metrics_multi_hop_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Multi Hop Metrics V1 Metrics Multi Hop Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/community": { "get": { "tags": [ "metrics" ], "summary": "Get Community Metrics", "description": "Return community summary usage metrics.", "operationId": "get_community_metrics_v1_metrics_community_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Community Metrics V1 Metrics Community Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/classification": { "get": { "tags": [ "metrics" ], "summary": "Get Classification Metrics", "description": "Return query mode classification metrics.", "operationId": "get_classification_metrics_v1_metrics_classification_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Classification Metrics V1 Metrics Classification Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/disambiguation": { "get": { "tags": [ "metrics" ], "summary": "Get Disambiguation Metrics", "description": "Return entity disambiguation recall metrics.", "operationId": "get_disambiguation_metrics_v1_metrics_disambiguation_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Disambiguation Metrics V1 Metrics Disambiguation Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/latency": { "get": { "tags": [ "metrics" ], "summary": "Get Latency Metrics", "description": "Return query latency percentiles (P50, P95, P99).", "operationId": "get_latency_metrics_v1_metrics_latency_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Latency Metrics V1 Metrics Latency Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/metrics/incremental-updates": { "get": { "tags": [ "metrics" ], "summary": "Get Incremental Update Metrics", "description": "Return incremental pipeline update metrics.", "operationId": "get_incremental_update_metrics_v1_metrics_incremental_updates_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Incremental Update Metrics V1 Metrics Incremental Updates Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/costs": { "get": { "tags": [ "metrics" ], "summary": "Get Costs", "description": "Return accumulated LLM cost statistics.\n\nIncludes total costs, per-session breakdowns, and per-operation breakdowns.\nRequires authentication.", "operationId": "get_costs_v1_costs_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Costs V1 Costs Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/statistics": { "get": { "tags": [ "dashboard" ], "summary": "Get Agent Statistics", "description": "Return aggregate agent statistics and a ranked leaderboard.", "operationId": "get_agent_statistics_v1_statistics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/trends": { "get": { "tags": [ "dashboard" ], "summary": "Get Agent Trends", "description": "Return per-agent rating history and trend metrics.", "operationId": "get_agent_trends_v1_trends_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendsResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "dashboard" ], "summary": "Get Agent Detail", "description": "Return comprehensive data for a single agent. Returns 404 if agent not found.", "operationId": "get_agent_detail_v1_agents__agent_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/ci-summary": { "get": { "tags": [ "dashboard" ], "summary": "Get Ci Summary Stats", "description": "Return latest CI eval and E2E summary stats.\n\nResponse shape:\n{\n \"eval\": {\n \"timestamp\": \"...\",\n \"entity_recall_avg\": 0.0,\n \"retrieval_recall_avg\": 0.0,\n \"classification_accuracy\": 0.0,\n \"total_queries\": 150,\n \"error_rate\": 0.0,\n \"modes\": { \"naive\": {...}, ... }\n },\n \"e2e\": {\n \"timestamp\": \"...\",\n \"passed\": true,\n \"total_tests\": 5,\n \"passed_tests\": 5,\n \"pass_rate\": 1.0\n }\n}", "operationId": "get_ci_summary_stats_v1_ci_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Ci Summary Stats V1 Ci Summary Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/dashboard/overview": { "get": { "tags": [ "dashboard" ], "summary": "Get Dashboard Overview", "description": "Return a unified dashboard overview combining all performance dimensions.\n\nSections:\n- agent_ratings: Glicko leaderboard summary (top agents, total games, avg rating)\n- query_performance: Latency percentiles, cache hit rate, multi-hop success,\n disambiguation recall, community usage, mode classification\n- cost_summary: Total LLM token usage and estimated costs by operation\n- feedback: Satisfaction rate, thumbs up/down counts, star rating average\n- eval: Query success/error rates, follow-up rate, mode distribution\n- ci: Latest CI eval and E2E test results\n- incremental_updates: Pipeline update success rate and merge statistics\n- data_analysis: Workspace file counts, sizes, type breakdown, lineage edges", "operationId": "get_dashboard_overview_v1_dashboard_overview_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Dashboard Overview V1 Dashboard Overview Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/dashboard/agent-comparison": { "get": { "tags": [ "dashboard" ], "summary": "Get Agent Comparison", "description": "Compare all agents side-by-side with ratings, win rates, and trend direction.\n\nReturns a list of agents with their current rating, trend direction,\nwin rate, and confidence interval \u2014 useful for quick visual comparison.", "operationId": "get_agent_comparison_v1_dashboard_agent_comparison_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Agent Comparison V1 Dashboard Agent Comparison Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/sessions/{session_id}/feedback": { "post": { "tags": [ "feedback" ], "summary": "Submit Feedback", "description": "Submit user feedback for a query response.\n\nAllows users to rate answers with thumbs up/down or 1-5 stars,\nand optionally provide comments. Feedback is stored for analytics\nand continuous improvement.\n\nArgs:\n session_id: The session ID containing the query\n payload: Feedback request with rating, comment, and metadata\n\nReturns:\n Confirmation of feedback submission with feedback ID", "operationId": "submit_feedback_v1_sessions__session_id__feedback_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/eval/queries": { "get": { "tags": [ "eval" ], "summary": "Get Eval Queries", "description": "Return a paginated list of query execution records with optional filtering and sorting.", "operationId": "get_eval_queries_v1_eval_queries_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Page Size" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "timestamp", "title": "Sort By" } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Sort Order" } }, { "name": "filter_mode", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filter Mode" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalQueryListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/eval/queries/{query_id}": { "get": { "tags": [ "eval" ], "summary": "Get Eval Query Detail", "description": "Return the full execution record for a single query by query_id.", "operationId": "get_eval_query_detail_v1_eval_queries__query_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "query_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Query Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryExecutionRecord" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/config/options": { "get": { "tags": [ "config" ], "summary": "Get Config Options", "description": "Return available configuration options.\n\nPublic endpoint \u2014 no auth required so the frontend can populate\nselectors before the user has created a session.", "operationId": "get_config_options_v1_config_options_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigOptionsResponse" } } } } } } }, "/v1/cache/stats": { "get": { "tags": [ "cache" ], "summary": "Get Cache Stats", "description": "Return precomputed query cache statistics.\n\nIncludes hit rate, total hits/misses, and cache effectiveness metrics.\nRequires authentication.", "operationId": "get_cache_stats_v1_cache_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Get Cache Stats V1 Cache Stats Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/cache/invalidate": { "post": { "tags": [ "cache" ], "summary": "Invalidate Cache", "description": "Invalidate precomputed query cache for a database.\n\nCall this after graph updates to ensure fresh results.\nRequires authentication.\n\nArgs:\n database: Database name to invalidate (default: \"default\")\n\nReturns:\n Number of cache entries invalidated", "operationId": "invalidate_cache_v1_cache_invalidate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "database", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Database" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Invalidate Cache V1 Cache Invalidate Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sessions/{session_id}/cache": { "delete": { "tags": [ "cache" ], "summary": "Clear Session Cache", "description": "Clear all cached query results for a specific session.\n\nUse this when cached results from failed queries prevent re-execution.\nRequires authentication.\n\nArgs:\n session_id: Session whose query cache should be cleared.\n\nReturns:\n Number of cache entries cleared.", "operationId": "clear_session_cache_v1_sessions__session_id__cache_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Clear Session Cache V1 Sessions Session Id Cache Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cache/query": { "delete": { "tags": [ "cache" ], "summary": "Clear Query Cache", "description": "Clear cached results for a specific question.\n\nRemoves the question from both the precomputed cache and, if a\nsession_id is provided, the per-session query cache. This lets\nusers retry a query that previously returned a cached error.\n\nArgs:\n question: The exact question text to evict.\n database: Database scope for the precomputed cache (default: \"default\").\n session_id: Optional session ID to also clear the per-session entry.\n\nReturns:\n Summary of entries cleared from each cache layer.", "operationId": "clear_query_cache_v1_cache_query_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "question", "in": "query", "required": true, "schema": { "type": "string", "title": "Question" } }, { "name": "database", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Database" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Clear Query Cache V1 Cache Query Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/": { "get": { "tags": [ "tenants" ], "summary": "List Tenants", "description": "List all registered tenants with their statuses.", "operationId": "list_tenants_v1_tenants__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TenantRecord" }, "type": "array", "title": "Response List Tenants V1 Tenants Get" } } } } } }, "post": { "tags": [ "tenants" ], "summary": "Register Tenant", "description": "Register a new tenant with the given isolation strategy.\n\nReturns 409 if a tenant with the same ID already exists.\nReturns 500 if database creation fails for database-isolation tenants.", "operationId": "register_tenant_v1_tenants__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTenantRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecord" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}": { "get": { "tags": [ "tenants" ], "summary": "Get Tenant", "description": "Get details for a specific tenant. Returns 404 if not found.", "operationId": "get_tenant_v1_tenants__tenant_id__get", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecord" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}/suspend": { "put": { "tags": [ "tenants" ], "summary": "Suspend Tenant", "description": "Suspend a tenant. Requires authentication.", "operationId": "suspend_tenant_v1_tenants__tenant_id__suspend_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecord" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}/delete": { "put": { "tags": [ "tenants" ], "summary": "Delete Tenant", "description": "Soft-delete a tenant. Requires authentication.", "operationId": "delete_tenant_v1_tenants__tenant_id__delete_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRecord" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}/permissions/{user_id}": { "put": { "tags": [ "tenants" ], "summary": "Update Permissions", "description": "Grant or revoke tenant permissions for a user. Requires authentication.\n\nSets the permission_level for the given user on the specified tenant.\nReturns 404 if the tenant is not found.", "operationId": "update_permissions_v1_tenants__tenant_id__permissions__user_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Update Permissions V1 Tenants Tenant Id Permissions User Id Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}/migrate": { "post": { "tags": [ "tenants" ], "summary": "Migrate Tenant Data", "description": "Trigger data migration for a tenant from the specified team's data.\n\nReturns 404 if the tenant is not found.", "operationId": "migrate_tenant_data_v1_tenants__tenant_id__migrate_post", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/{tenant_id}/isolation": { "get": { "tags": [ "tenants" ], "summary": "Verify Isolation", "description": "Verify data isolation for a tenant. Returns 404 if tenant not found.", "operationId": "verify_isolation_v1_tenants__tenant_id__isolation_get", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsolationVerificationResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tenants/federated-query": { "post": { "tags": [ "tenants" ], "summary": "Federated Query", "description": "Execute a federated query across multiple tenant partitions.\n\nReturns 403 if the user is unauthorized for any specified tenant.\nReturns 503 if all tenants are unavailable.", "operationId": "federated_query_v1_tenants_federated_query_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedQueryResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/events/": { "get": { "tags": [ "event-sourcing" ], "summary": "List Events", "description": "List graph events with optional filters and cursor-based pagination.\n\nSupports filtering by actor_id, time range, mutation_type, and\naffected_entity_id. Returns paginated results with cursor navigation.\n\nReturns 400 if start_time is after end_time.", "operationId": "list_events_v1_events__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "actor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by actor identifier", "title": "Actor Id" }, "description": "Filter by actor identifier" }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter events from this timestamp (inclusive)", "title": "Start Time" }, "description": "Filter events from this timestamp (inclusive)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter events up to this timestamp (inclusive)", "title": "End Time" }, "description": "Filter events up to this timestamp (inclusive)" }, { "name": "mutation_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by mutation type", "title": "Mutation Type" }, "description": "Filter by mutation type" }, { "name": "affected_entity_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by affected entity identifier", "title": "Affected Entity Id" }, "description": "Filter by affected entity identifier" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Number of events per page", "default": 50, "title": "Page Size" }, "description": "Number of events per page" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Cursor for pagination (sequence number)", "title": "Cursor" }, "description": "Cursor for pagination (sequence number)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventQueryResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/events/stats": { "get": { "tags": [ "event-sourcing" ], "summary": "Get Stats", "description": "Return total event count and timestamp range of the event store.", "operationId": "get_stats_v1_events_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStoreStats" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/events/replay": { "post": { "tags": [ "event-sourcing" ], "summary": "Replay Events", "description": "Trigger a dry-run replay to the specified target timestamp.\n\nAlways runs in dry-run mode (computes state in memory without writing).\nAuthentication is required; admin role check is a placeholder for now.\n\nReturns a ReplayResult with event counts and reconstructed state summary.", "operationId": "replay_events_v1_events_replay_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/diffusion/discovery-priority": { "get": { "tags": [ "diffusion" ], "summary": "Get Discovery Priority", "description": "Return discovery priority metrics with optional team and time range filters.\n\nReturns 400 if start_time is after end_time.", "operationId": "get_discovery_priority_v1_diffusion_discovery_priority_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by team name", "title": "Team" }, "description": "Filter by team name" }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter from this timestamp (inclusive)", "title": "Start Time" }, "description": "Filter from this timestamp (inclusive)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter up to this timestamp (inclusive)", "title": "End Time" }, "description": "Filter up to this timestamp (inclusive)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveryRecord" }, "title": "Response Get Discovery Priority V1 Diffusion Discovery Priority Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/diffusion/confirmation-latency": { "get": { "tags": [ "diffusion" ], "summary": "Get Confirmation Latency", "description": "Return confirmation latency metrics with optional team and time range filters.\n\nReturns 400 if start_time is after end_time.", "operationId": "get_confirmation_latency_v1_diffusion_confirmation_latency_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by team name", "title": "Team" }, "description": "Filter by team name" }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter from this timestamp (inclusive)", "title": "Start Time" }, "description": "Filter from this timestamp (inclusive)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter up to this timestamp (inclusive)", "title": "End Time" }, "description": "Filter up to this timestamp (inclusive)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationLatencyResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/diffusion/knowledge-overlap": { "get": { "tags": [ "diffusion" ], "summary": "Get Knowledge Overlap", "description": "Return knowledge overlap and unique contribution metrics.\n\nOptionally filter by team pair and time range.\nReturns 400 if start_time is after end_time.", "operationId": "get_knowledge_overlap_v1_diffusion_knowledge_overlap_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team_a", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First team in pair filter", "title": "Team A" }, "description": "First team in pair filter" }, { "name": "team_b", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second team in pair filter", "title": "Team B" }, "description": "Second team in pair filter" }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter from this timestamp (inclusive)", "title": "Start Time" }, "description": "Filter from this timestamp (inclusive)" }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter up to this timestamp (inclusive)", "title": "End Time" }, "description": "Filter up to this timestamp (inclusive)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverlapResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/diffusion/team/{team}/summary": { "get": { "tags": [ "diffusion" ], "summary": "Get Team Summary", "description": "Return aggregated diffusion metrics summary for a single team.\n\nReturns 404 if the team has no User_Context_Nodes in the graph.", "operationId": "get_team_summary_v1_diffusion_team__team__summary_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "team", "in": "path", "required": true, "schema": { "type": "string", "title": "Team" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/temporal-viz/bounds": { "get": { "tags": [ "temporal-viz" ], "summary": "Get Temporal Bounds", "description": "Return the temporal bounds of the Context_Graph.\n\nReturns the earliest and latest valid_from timestamps across all\nnodes and relationships. Returns null values if the graph is empty.", "operationId": "get_temporal_bounds_v1_temporal_viz_bounds_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporalBounds" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/temporal-viz/snapshot": { "get": { "tags": [ "temporal-viz" ], "summary": "Get Snapshot", "description": "Return a graph snapshot at a specific timestamp.\n\nIncludes X-Total-Node-Count and X-Total-Relationship-Count response headers.", "operationId": "get_snapshot_v1_temporal_viz_snapshot_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "timestamp", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 UTC timestamp for the graph snapshot", "title": "Timestamp" }, "description": "ISO 8601 UTC timestamp for the graph snapshot" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphSnapshot" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/temporal-viz/snapshot/range": { "get": { "tags": [ "temporal-viz" ], "summary": "Get Snapshot Range", "description": "Return a graph snapshot for a time range.\n\nIncludes X-Total-Node-Count and X-Total-Relationship-Count response headers.\nReturns 400 if start_time is after end_time.", "operationId": "get_snapshot_range_v1_temporal_viz_snapshot_range_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "start_time", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 UTC start timestamp for the range", "title": "Start Time" }, "description": "ISO 8601 UTC start timestamp for the range" }, { "name": "end_time", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 UTC end timestamp for the range", "title": "End Time" }, "description": "ISO 8601 UTC end timestamp for the range" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphSnapshot" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/temporal-viz/keyframes": { "get": { "tags": [ "temporal-viz" ], "summary": "Get Keyframes", "description": "Return animation keyframes over a time range.\n\nReturns 400 if start_time is after end_time or if the number of\nkeyframes would exceed 365.", "operationId": "get_keyframes_v1_temporal_viz_keyframes_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "start_time", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 UTC start timestamp for the animation range", "title": "Start Time" }, "description": "ISO 8601 UTC start timestamp for the animation range" }, { "name": "end_time", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 UTC end timestamp for the animation range", "title": "End Time" }, "description": "ISO 8601 UTC end timestamp for the animation range" }, { "name": "step_interval", "in": "query", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "Step interval in seconds between keyframes", "title": "Step Interval" }, "description": "Step interval in seconds between keyframes" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Keyframe" }, "title": "Response Get Keyframes V1 Temporal Viz Keyframes Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/status/full": { "get": { "tags": [ "status" ], "summary": "Full Status", "operationId": "full_status_v1_status_full_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/metrics": { "get": { "tags": [ "metrics" ], "summary": "Prometheus Metrics", "operationId": "prometheus_metrics_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/keys": { "get": { "tags": [ "api-keys" ], "summary": "List Api Keys", "description": "List all active API keys for the authenticated user.", "operationId": "list_api_keys_v1_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKeysResponse" } } } } } }, "post": { "tags": [ "api-keys" ], "summary": "Create Api Key", "description": "Generate a new API key for the authenticated user.", "operationId": "create_api_key_v1_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/keys/{key_id}": { "delete": { "tags": [ "api-keys" ], "summary": "Revoke Api Key", "description": "Revoke an API key.", "operationId": "revoke_api_key_v1_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AgentDetailResponse": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "metadata": { "$ref": "#/components/schemas/LeaderboardEntry" }, "history": { "items": { "$ref": "#/components/schemas/HistoryEntry" }, "type": "array", "title": "History" }, "metrics": { "$ref": "#/components/schemas/TrendMetrics" }, "feedback_distribution": { "$ref": "#/components/schemas/FeedbackDistribution" }, "sample_queries": { "$ref": "#/components/schemas/SampleQueries" } }, "type": "object", "required": [ "agent_id", "metadata", "history", "metrics", "feedback_distribution", "sample_queries" ], "title": "AgentDetailResponse" }, "AgentTrend": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "history": { "items": { "$ref": "#/components/schemas/HistoryEntry" }, "type": "array", "title": "History" }, "metrics": { "$ref": "#/components/schemas/TrendMetrics" } }, "type": "object", "required": [ "agent_id", "history", "metrics" ], "title": "AgentTrend" }, "AnalyzeCentralityRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for Neo4j driver access" }, "centrality_type": { "type": "string", "title": "Centrality Type", "description": "Centrality type: 'degree', 'betweenness', or 'pagerank'", "default": "degree" } }, "type": "object", "required": [ "session_id" ], "title": "AnalyzeCentralityRequest", "description": "Request body for the centrality analysis child-cell endpoint." }, "Annotation": { "properties": { "annotation_id": { "type": "string", "title": "Annotation Id", "description": "Unique identifier for the annotation" }, "file_id": { "type": "string", "title": "File Id", "description": "Identifier of the annotated document" }, "column_name": { "type": "string", "title": "Column Name", "description": "Name of the annotated column" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "Identifier of the target entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the target entity" }, "note": { "type": "string", "title": "Note", "description": "Free-text note provided by the user" }, "created_by": { "type": "string", "title": "Created By", "description": "User ID who created the annotation" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the annotation was created" } }, "type": "object", "required": [ "annotation_id", "file_id", "column_name", "entity_id", "entity_name", "note", "created_by", "created_at" ], "title": "Annotation", "description": "A user-created annotation linking a document column to a graph entity.\n\nRequirements: 5.1, 5.2" }, "AnnotationInput": { "properties": { "column_name": { "type": "string", "title": "Column Name", "description": "Name of the column to annotate" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "Identifier of the target entity" }, "note": { "type": "string", "title": "Note", "description": "Optional free-text note", "default": "" } }, "type": "object", "required": [ "column_name", "entity_id" ], "title": "AnnotationInput", "description": "Input model for creating a single annotation.\n\nRequirements: 5.1, 5.2" }, "Body_upload_file_v1_my_files_upload_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_v1_my_files_upload_post" }, "BranchCellRequest": { "properties": { "query": { "type": "string", "minLength": 1, "title": "Query", "description": "Natural language query" }, "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for query execution" }, "search_depth": { "type": "string", "title": "Search Depth", "description": "Search depth: 'fast', 'balanced', or 'deep'", "default": "balanced" } }, "type": "object", "required": [ "query", "session_id" ], "title": "BranchCellRequest" }, "CandidateListResult": { "properties": { "candidates": { "items": { "$ref": "#/components/schemas/CandidateStatisticalEdge" }, "type": "array", "title": "Candidates", "description": "List of candidate statistical edges matching the query" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of candidates matching the query" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page; None if no more results" } }, "type": "object", "required": [ "candidates", "total_count" ], "title": "CandidateListResult", "description": "Paginated result set for candidate statistical edge listing.\n\nContains the matching candidates, total count, and an optional cursor\nfor fetching the next page.\n\nRequirements: 6.1, 6.7" }, "CandidateStatisticalEdge": { "properties": { "candidate_id": { "type": "string", "title": "Candidate Id", "description": "Unique identifier for this candidate edge" }, "source_entity_id": { "type": "string", "title": "Source Entity Id", "description": "Identifier of the source entity in the Context Graph" }, "target_entity_id": { "type": "string", "title": "Target Entity Id", "description": "Identifier of the target entity in the Context Graph" }, "test_type": { "type": "string", "title": "Test Type", "description": "Type of statistical test performed: 'pearson', 'spearman', 'chi_squared', or 'point_biserial'" }, "p_value": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "P Value", "description": "P-value from the statistical test" }, "effect_size": { "type": "number", "title": "Effect Size", "description": "Effect size measure from the statistical test" }, "ci_lower": { "type": "number", "title": "Ci Lower", "description": "Lower bound of the confidence interval" }, "ci_upper": { "type": "number", "title": "Ci Upper", "description": "Upper bound of the confidence interval" }, "sample_size": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Sample Size", "description": "Number of samples used in the statistical test" }, "source_dataset_id": { "type": "string", "title": "Source Dataset Id", "description": "Identifier of the dataset from which the correlation was discovered" }, "source_column_a": { "type": "string", "title": "Source Column A", "description": "Name of the first column in the tested pair" }, "source_column_b": { "type": "string", "title": "Source Column B", "description": "Name of the second column in the tested pair" }, "corrected_threshold": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Corrected Threshold", "description": "Bonferroni-corrected significance threshold applied to this test" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "rejected" ], "title": "Status", "description": "Review status: 'pending' awaiting review, 'confirmed' accepted into graph, 'rejected' discarded", "default": "pending" }, "rejection_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rejection Reason", "description": "User-provided reason for rejecting the candidate; None if not rejected" }, "discovered_at": { "type": "string", "format": "date-time", "title": "Discovered At", "description": "Timestamp when the candidate was discovered by the Auto Discovery Service" }, "acted_on_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Acted On By", "description": "Identifier of the user who confirmed or rejected the candidate; None if pending" }, "acted_on_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Acted On At", "description": "Timestamp when the candidate was confirmed or rejected; None if pending" }, "is_duplicate": { "type": "boolean", "title": "Is Duplicate", "description": "Whether this candidate duplicates an existing Statistical Edge between the same entity pair with the same test type", "default": false }, "existing_edge_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Existing Edge Id", "description": "Identifier of the existing Statistical Edge if this candidate is a duplicate; None otherwise" } }, "type": "object", "required": [ "candidate_id", "source_entity_id", "target_entity_id", "test_type", "p_value", "effect_size", "ci_lower", "ci_upper", "sample_size", "source_dataset_id", "source_column_a", "source_column_b", "corrected_threshold", "discovered_at" ], "title": "CandidateStatisticalEdge", "description": "A proposed statistical edge discovered by automated correlation scanning.\n\nRepresents a statistically significant correlation between two columns\nin an ingested tabular dataset, where both columns resolve to known\nentities in the Context Graph. Awaits user confirmation or rejection\nbefore being committed as a full Statistical Edge.\n\nRequirements: 5.4, 6.1, 6.7" }, "CellExpandKNNRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID to get the Neo4j driver from" }, "node_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Node Ids", "description": "Node IDs to expand from" }, "existing_node_ids": { "items": { "type": "string" }, "type": "array", "title": "Existing Node Ids", "description": "Already-visible node IDs to exclude" }, "max_depth": { "type": "integer", "maximum": 3.0, "minimum": 1.0, "title": "Max Depth", "description": "Traversal depth", "default": 1 }, "k": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "K", "description": "Max neighbors per seed node", "default": 10 } }, "type": "object", "required": [ "session_id", "node_ids" ], "title": "CellExpandKNNRequest" }, "CellExpandKNNResponse": { "properties": { "nodes": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Nodes" }, "edges": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Edges" }, "new_count": { "type": "integer", "title": "New Count" }, "expansion_level": { "type": "integer", "title": "Expansion Level" } }, "type": "object", "required": [ "nodes", "edges", "new_count", "expansion_level" ], "title": "CellExpandKNNResponse" }, "CellResponse": { "properties": { "cell_id": { "type": "string", "format": "uuid", "title": "Cell Id" }, "thread_id": { "type": "string", "title": "Thread Id" }, "parent_cell_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Cell Id" }, "query": { "type": "string", "title": "Query" }, "response": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response" }, "status": { "$ref": "#/components/schemas/CellStatus" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "execution_time_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Execution Time Ms" }, "search_depth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Depth" }, "context": { "additionalProperties": true, "type": "object", "title": "Context" }, "child_cell_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Child Cell Ids" }, "outputs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Outputs" } }, "type": "object", "required": [ "cell_id", "thread_id", "parent_cell_id", "query", "response", "status", "error", "created_at", "updated_at", "execution_time_ms", "search_depth", "context", "child_cell_ids" ], "title": "CellResponse" }, "CellStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ], "title": "CellStatus", "description": "Status of a cell in its lifecycle." }, "CellTreeResponse": { "properties": { "thread_id": { "type": "string", "title": "Thread Id" }, "root_cell_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Root Cell Id" }, "cells": { "additionalProperties": { "$ref": "#/components/schemas/CellResponse" }, "type": "object", "title": "Cells" }, "active_cell_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Active Cell Id" }, "permission": { "type": "string", "title": "Permission", "default": "owner" } }, "type": "object", "required": [ "thread_id", "root_cell_id", "cells", "active_cell_id" ], "title": "CellTreeResponse" }, "CellWithContextResponse": { "properties": { "cell_id": { "type": "string", "format": "uuid", "title": "Cell Id" }, "thread_id": { "type": "string", "title": "Thread Id" }, "parent_cell_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Cell Id" }, "query": { "type": "string", "title": "Query" }, "response": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response" }, "status": { "$ref": "#/components/schemas/CellStatus" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "execution_time_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Execution Time Ms" }, "search_depth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Depth" }, "context": { "additionalProperties": true, "type": "object", "title": "Context" }, "child_cell_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Child Cell Ids" }, "outputs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Outputs" }, "conversation_context": { "additionalProperties": true, "type": "object", "title": "Conversation Context" } }, "type": "object", "required": [ "cell_id", "thread_id", "parent_cell_id", "query", "response", "status", "error", "created_at", "updated_at", "execution_time_ms", "search_depth", "context", "child_cell_ids", "conversation_context" ], "title": "CellWithContextResponse" }, "ColumnMappingSuggestion": { "properties": { "column_name": { "type": "string", "title": "Column Name", "description": "Name of the document column" }, "candidates": { "items": { "$ref": "#/components/schemas/EntityCandidate" }, "type": "array", "title": "Candidates", "description": "Ranked list of candidate entity matches, sorted by confidence descending" } }, "type": "object", "required": [ "column_name", "candidates" ], "title": "ColumnMappingSuggestion", "description": "Mapping suggestions for a single document column.\n\nContains ranked candidate entity matches for a given column name.\n\nRequirements: 2.2" }, "ColumnSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "dtype": { "type": "string", "title": "Dtype" }, "stats": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Stats" }, "unique_count": { "type": "integer", "title": "Unique Count", "default": 0 } }, "type": "object", "required": [ "name", "dtype" ], "title": "ColumnSchema", "description": "Schema for a single column." }, "CommunityEvolutionEvent": { "type": "string", "enum": [ "stable", "emergence", "dissolution", "merge", "split" ], "title": "CommunityEvolutionEvent", "description": "Event types for community evolution across consecutive time snapshots.\n\nClassifies how a community changed between two consecutive temporal\nsnapshots: remained stable, emerged, dissolved, merged with others,\nor split into multiple communities.\n\nRequirements: 2.3, 2.4, 2.5, 2.6, 2.7" }, "CommunityEvolutionRecord": { "properties": { "snapshot_timestamp_before": { "type": "string", "title": "Snapshot Timestamp Before", "description": "ISO 8601 UTC timestamp of the earlier snapshot" }, "snapshot_timestamp_after": { "type": "string", "title": "Snapshot Timestamp After", "description": "ISO 8601 UTC timestamp of the later snapshot" }, "event_type": { "$ref": "#/components/schemas/CommunityEvolutionEvent", "description": "Type of evolution event: stable, emergence, dissolution, merge, or split" }, "community_id_before": { "anyOf": [ { "type": "integer" }, { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Community Id Before", "description": "Community ID(s) in the earlier snapshot; None for emergence, list for merge" }, "community_id_after": { "anyOf": [ { "type": "integer" }, { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Community Id After", "description": "Community ID(s) in the later snapshot; None for dissolution, list for split" }, "members_gained": { "items": { "type": "string" }, "type": "array", "title": "Members Gained", "description": "Entity IDs added to the community between snapshots", "default": [] }, "members_lost": { "items": { "type": "string" }, "type": "array", "title": "Members Lost", "description": "Entity IDs removed from the community between snapshots", "default": [] }, "jaccard_similarity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Jaccard Similarity", "description": "Jaccard similarity between entity sets across snapshots; None for emergence/dissolution" }, "source_community_ids": { "items": { "type": "integer" }, "type": "array", "title": "Source Community Ids", "description": "Community IDs from the earlier snapshot that merged into the resulting community", "default": [] }, "resulting_community_ids": { "items": { "type": "integer" }, "type": "array", "title": "Resulting Community Ids", "description": "Community IDs in the later snapshot that resulted from a split", "default": [] } }, "type": "object", "required": [ "snapshot_timestamp_before", "snapshot_timestamp_after", "event_type" ], "title": "CommunityEvolutionRecord", "description": "A record tracking how a community changed between consecutive snapshots.\n\nCaptures the snapshot timestamps, the event type, community linkages\nbefore and after, members gained and lost, Jaccard similarity, and\nsource/resulting community identifiers for merge and split events.\n\nRequirements: 2.3, 2.4, 2.5, 2.6, 2.7, 5.2" }, "ConfidenceInterval": { "properties": { "lower": { "type": "number", "title": "Lower" }, "upper": { "type": "number", "title": "Upper" }, "confidence_level": { "type": "number", "title": "Confidence Level", "default": 0.95 } }, "type": "object", "required": [ "lower", "upper" ], "title": "ConfidenceInterval" }, "ConfigOptionsResponse": { "properties": { "models": { "items": { "$ref": "#/components/schemas/ModelOption" }, "type": "array", "title": "Models" }, "llm_providers": { "items": { "$ref": "#/components/schemas/ProviderOption" }, "type": "array", "title": "Llm Providers" }, "databases": { "items": { "$ref": "#/components/schemas/DatabaseOption" }, "type": "array", "title": "Databases", "default": [] } }, "type": "object", "required": [ "models", "llm_providers" ], "title": "ConfigOptionsResponse", "description": "Response for /v1/config/options." }, "ConfirmMappingRequest": { "properties": { "column_name": { "type": "string", "title": "Column Name", "description": "Name of the column to map" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "Identifier of the target entity" }, "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the confirming user" } }, "type": "object", "required": [ "column_name", "entity_id", "user_id" ], "title": "ConfirmMappingRequest", "description": "Request body for confirming a column-to-entity mapping." }, "ConfirmRequest": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the confirming user" } }, "type": "object", "required": [ "user_id" ], "title": "ConfirmRequest", "description": "Request body for confirming a candidate." }, "ConfirmationLatencyResult": { "properties": { "per_relationship": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Per Relationship", "description": "Per-relationship latency details: [{relationship_id, latencies: [(team, hours)]}]" }, "mean_latency_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Latency Hours", "description": "Mean confirmation latency in hours across all multi-team relationships; None if no multi-team relationships exist" }, "median_latency_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Median Latency Hours", "description": "Median confirmation latency in hours across all multi-team relationships; None if no multi-team relationships exist" }, "p90_latency_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "P90 Latency Hours", "description": "90th percentile confirmation latency in hours across all multi-team relationships; None if no multi-team relationships exist" }, "single_team_count": { "type": "integer", "title": "Single Team Count", "description": "Number of relationships contributed by only one team, excluded from latency calculations" } }, "type": "object", "required": [ "per_relationship", "single_team_count" ], "title": "ConfirmationLatencyResult", "description": "Aggregated confirmation latency metrics across relationships.\n\nReports per-relationship latencies (time deltas between the discovering\nteam and each subsequent team), along with aggregate statistics (mean,\nmedian, 90th percentile) computed over all multi-team relationships.\n\nRequirements: 9.1, 9.2, 9.3" }, "ConfirmedMapping": { "properties": { "mapping_id": { "type": "string", "title": "Mapping Id", "description": "Deterministic ID: hash(file_id + column_name + entity_id)" }, "file_id": { "type": "string", "title": "File Id", "description": "Identifier of the source document" }, "column_name": { "type": "string", "title": "Column Name", "description": "Name of the mapped column" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "Identifier of the target entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the target entity" }, "confirmed_by": { "type": "string", "title": "Confirmed By", "description": "User ID who confirmed the mapping" }, "confirmed_at": { "type": "string", "format": "date-time", "title": "Confirmed At", "description": "Timestamp when the mapping was confirmed" } }, "type": "object", "required": [ "mapping_id", "file_id", "column_name", "entity_id", "entity_name", "confirmed_by", "confirmed_at" ], "title": "ConfirmedMapping", "description": "A user-confirmed column-to-entity mapping with provenance.\n\nPersisted as a MAPS_COLUMN relationship in Neo4j between the Document\nnode and the Entity node.\n\nRequirements: 2.2" }, "ConnectedEntity": { "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "Unique identifier of the connected entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the entity" }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type/category of the entity (e.g., Protein, Disease)" }, "relationship_kind": { "type": "string", "title": "Relationship Kind", "description": "Kind of connection: 'column_mapping', 'statistical_edge', 'annotation', or 'ingestion'" }, "confidence": { "type": "number", "title": "Confidence", "description": "Confidence score of the connection" }, "source_type": { "type": "string", "title": "Source Type", "description": "Origin of the connection: 'user_confirmed' or 'system_inferred'" } }, "type": "object", "required": [ "entity_id", "entity_name", "entity_type", "relationship_kind", "confidence", "source_type" ], "title": "ConnectedEntity", "description": "An entity connected to a document through any relationship type.\n\nRequirements: 3.2" }, "ContradictionEvent": { "properties": { "entity_pair": { "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array", "maxItems": 2, "minItems": 2, "title": "Entity Pair", "description": "Ordered pair of entity identifiers involved in the contradiction" }, "relationship_types": { "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array", "maxItems": 2, "minItems": 2, "title": "Relationship Types", "description": "The two conflicting relationship types (e.g., ('UPREGULATES', 'DOWNREGULATES'))" }, "detected_at": { "type": "string", "title": "Detected At", "description": "ISO 8601 UTC timestamp when the contradiction was detected" } }, "type": "object", "required": [ "entity_pair", "relationship_types", "detected_at" ], "title": "ContradictionEvent", "description": "A contradiction detection event within a keyframe interval.\n\nRecords the entity pair, the conflicting relationship types, and the\ndetection timestamp.\n\nRequirements: 13.2" }, "CreateAnnotationsRequest": { "properties": { "annotations": { "items": { "$ref": "#/components/schemas/AnnotationInput" }, "type": "array", "title": "Annotations", "description": "List of annotation inputs" }, "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the user creating annotations" } }, "type": "object", "required": [ "annotations", "user_id" ], "title": "CreateAnnotationsRequest", "description": "Request body for creating one or more annotations." }, "CreateCellRequest": { "properties": { "query": { "type": "string", "minLength": 1, "title": "Query", "description": "Natural language query" }, "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for query execution" }, "parent_cell_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Cell Id", "description": "Parent cell to attach to" }, "search_depth": { "type": "string", "title": "Search Depth", "description": "Search depth: 'fast' (discovery only), 'balanced' (default), or 'deep' (full expansion + cypher)", "default": "balanced" } }, "type": "object", "required": [ "query", "session_id" ], "title": "CreateCellRequest" }, "CreateKeyRequest": { "properties": { "expires_days": { "type": "integer", "maximum": 365.0, "minimum": 1.0, "title": "Expires Days", "default": 90 }, "label": { "type": "string", "maxLength": 100, "title": "Label", "description": "Optional label for this key", "default": "" } }, "type": "object", "title": "CreateKeyRequest" }, "CreateKeyResponse": { "properties": { "key": { "type": "string", "title": "Key" }, "key_id": { "type": "string", "title": "Key Id" }, "expires_at": { "type": "string", "title": "Expires At" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "key", "key_id", "expires_at", "label" ], "title": "CreateKeyResponse" }, "CreateThreadRequest": { "properties": { "thread_id": { "type": "string", "minLength": 1, "title": "Thread Id", "description": "Unique thread identifier" }, "org_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Org Id", "description": "Organization ID to associate with" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id", "description": "Owner user ID" }, "permission": { "type": "string", "title": "Permission", "description": "Default permission: read, write, or owner", "default": "read" } }, "type": "object", "required": [ "thread_id" ], "title": "CreateThreadRequest" }, "DAGEdgeResponse": { "properties": { "source": { "type": "string", "title": "Source" }, "target": { "type": "string", "title": "Target" } }, "type": "object", "required": [ "source", "target" ], "title": "DAGEdgeResponse" }, "DAGNodeResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "status": { "$ref": "#/components/schemas/CellStatus" } }, "type": "object", "required": [ "id", "label", "status" ], "title": "DAGNodeResponse" }, "DAGResponse": { "properties": { "thread_id": { "type": "string", "title": "Thread Id" }, "nodes": { "items": { "$ref": "#/components/schemas/DAGNodeResponse" }, "type": "array", "title": "Nodes" }, "edges": { "items": { "$ref": "#/components/schemas/DAGEdgeResponse" }, "type": "array", "title": "Edges" }, "cycles": { "items": { "type": "string" }, "type": "array", "title": "Cycles" }, "execution_order": { "items": { "type": "string" }, "type": "array", "title": "Execution Order" } }, "type": "object", "required": [ "thread_id", "nodes", "edges", "cycles", "execution_order" ], "title": "DAGResponse" }, "DLQListResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/DLQMessageResponse" }, "type": "array", "title": "Messages", "description": "List of DLQ messages" }, "count": { "type": "integer", "minimum": 0.0, "title": "Count", "description": "Number of messages returned" } }, "type": "object", "required": [ "messages", "count" ], "title": "DLQListResponse", "description": "Response model for listing DLQ messages." }, "DLQMessageResponse": { "properties": { "message_id": { "type": "string", "title": "Message Id", "description": "SQS message ID" }, "original_payload": { "additionalProperties": true, "type": "object", "title": "Original Payload", "description": "Original ingestion message payload" }, "failure_reason": { "type": "string", "title": "Failure Reason", "description": "Human-readable failure description" }, "failure_count": { "type": "integer", "minimum": 0.0, "title": "Failure Count", "description": "Number of failed processing attempts" }, "first_failure": { "type": "string", "title": "First Failure", "description": "Timestamp of first failure (ISO 8601)" }, "last_failure": { "type": "string", "title": "Last Failure", "description": "Timestamp of most recent failure (ISO 8601)" }, "source": { "type": "string", "title": "Source", "description": "Ingestion source identifier" }, "error_type": { "type": "string", "title": "Error Type", "description": "Classified error type category" } }, "type": "object", "required": [ "message_id", "original_payload", "failure_reason", "failure_count", "first_failure", "last_failure", "source", "error_type" ], "title": "DLQMessageResponse", "description": "Response model for a single DLQ message." }, "DLQRetryResponse": { "properties": { "message_id": { "type": "string", "title": "Message Id", "description": "Message ID that was retried" }, "success": { "type": "boolean", "title": "Success", "description": "Whether the message was re-enqueued" }, "detail": { "type": "string", "title": "Detail", "description": "Human-readable result description" } }, "type": "object", "required": [ "message_id", "success", "detail" ], "title": "DLQRetryResponse", "description": "Response model for DLQ message retry operation." }, "DatabaseOption": { "properties": { "value": { "type": "string", "title": "Value" }, "label": { "type": "string", "title": "Label" }, "type": { "type": "string", "title": "Type" }, "endpoint": { "type": "string", "title": "Endpoint", "default": "" }, "default": { "type": "boolean", "title": "Default", "default": false } }, "type": "object", "required": [ "value", "label", "type" ], "title": "DatabaseOption", "description": "A selectable database backend." }, "DatabaseStatsResponse": { "properties": { "node_count": { "type": "integer", "title": "Node Count", "description": "Total number of nodes in the database" }, "link_count": { "type": "integer", "title": "Link Count", "description": "Total number of relationships/links in the database" }, "node_types": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Node Types", "description": "Count of nodes by type/label" }, "degree_distribution": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Degree Distribution", "description": "Degree distribution histogram (degree -> count)" } }, "type": "object", "required": [ "node_count", "link_count", "node_types", "degree_distribution" ], "title": "DatabaseStatsResponse" }, "DatasetMetadata": { "properties": { "file_id": { "type": "string", "title": "File Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "type": "string", "title": "Description", "default": "" }, "source": { "type": "string", "title": "Source", "default": "" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "default": [] }, "extracted_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extracted Date" }, "extracted_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extracted Version" }, "inferred_topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inferred Topic" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "file_id", "display_name", "created_at", "updated_at" ], "title": "DatasetMetadata", "description": "Persisted metadata for a dataset." }, "DatasetMetadataInput": { "properties": { "display_name": { "type": "string", "title": "Display Name" }, "description": { "type": "string", "title": "Description", "default": "" }, "source": { "type": "string", "title": "Source", "default": "" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "default": [] } }, "type": "object", "required": [ "display_name" ], "title": "DatasetMetadataInput", "description": "Request body for creating/updating metadata." }, "DatasetSchema": { "properties": { "file_id": { "type": "string", "title": "File Id" }, "row_count": { "type": "integer", "title": "Row Count" }, "column_count": { "type": "integer", "title": "Column Count" }, "columns": { "items": { "$ref": "#/components/schemas/ColumnSchema" }, "type": "array", "title": "Columns" } }, "type": "object", "required": [ "file_id", "row_count", "column_count", "columns" ], "title": "DatasetSchema", "description": "Schema for an entire dataset." }, "DescribeDatasetRequest": { "properties": { "text": { "type": "string", "title": "Text" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Team" } }, "type": "object", "required": [ "text" ], "title": "DescribeDatasetRequest", "description": "User-provided free-text context about a dataset." }, "DetectCommunitiesRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for Neo4j driver access" }, "algorithm": { "type": "string", "title": "Algorithm", "description": "Algorithm: 'louvain' or 'label_propagation'", "default": "louvain" }, "min_community_size": { "type": "integer", "minimum": 1.0, "title": "Min Community Size", "description": "Minimum community size", "default": 2 } }, "type": "object", "required": [ "session_id" ], "title": "DetectCommunitiesRequest", "description": "Request body for the community detection child-cell endpoint." }, "DiscoveryRecord": { "properties": { "relationship_id": { "type": "string", "title": "Relationship Id", "description": "Identifier of the discovered relationship" }, "entity_pair": { "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array", "maxItems": 2, "minItems": 2, "title": "Entity Pair", "description": "Ordered pair of entity identifiers connected by the relationship" }, "relationship_type": { "type": "string", "title": "Relationship Type", "description": "Type of the discovered relationship (e.g., 'UPREGULATES')" }, "discovering_team": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "title": "Discovering Team", "description": "Team that discovered the relationship first; list if multiple teams share the earliest timestamp (co-discoverers)" }, "discovery_timestamp": { "type": "string", "title": "Discovery Timestamp", "description": "ISO 8601 UTC timestamp of the earliest provenance chain for this relationship" }, "subsequent_teams": { "items": { "type": "string" }, "type": "array", "title": "Subsequent Teams", "description": "Teams that contributed provenance chains after the discovering team" } }, "type": "object", "required": [ "relationship_id", "entity_pair", "relationship_type", "discovering_team", "discovery_timestamp", "subsequent_teams" ], "title": "DiscoveryRecord", "description": "A record identifying which team first discovered a relationship.\n\nCaptures the discovering team (or co-discoverers when multiple teams\nshare the earliest timestamp), the discovery timestamp, and the list\nof teams that subsequently contributed provenance for the same\nrelationship.\n\nRequirements: 8.1, 8.2" }, "DocumentConnectivity": { "properties": { "file_id": { "type": "string", "title": "File Id", "description": "Identifier of the document" }, "entities": { "items": { "$ref": "#/components/schemas/ConnectedEntity" }, "type": "array", "title": "Entities", "description": "List of connected entities for the current page" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of connected entities" }, "pending_candidates": { "type": "integer", "title": "Pending Candidates", "description": "Number of auto-discovery candidates pending review" }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-indexed)" }, "page_size": { "type": "integer", "title": "Page Size", "description": "Number of entities per page" } }, "type": "object", "required": [ "file_id", "entities", "total_count", "pending_candidates", "page", "page_size" ], "title": "DocumentConnectivity", "description": "Paginated view of all entities connected to a document.\n\nAggregates connections from column mappings, statistical edges,\nannotations, and ingestion relationships.\n\nRequirements: 3.2" }, "EnrichRequest": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the user initiating enrichment" } }, "type": "object", "required": [ "user_id" ], "title": "EnrichRequest", "description": "Request body for starting an enrichment workflow." }, "EntityCandidate": { "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "Unique identifier of the candidate entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the candidate entity" }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type/category of the entity (e.g., Protein, Disease)" }, "confidence": { "type": "number", "title": "Confidence", "description": "Match confidence score between 0 and 1" }, "match_method": { "type": "string", "title": "Match Method", "description": "Method used to find this match: 'exact', 'fuzzy', or 'embedding'" } }, "type": "object", "required": [ "entity_id", "entity_name", "entity_type", "confidence", "match_method" ], "title": "EntityCandidate", "description": "A candidate entity match for a document column.\n\nRepresents a potential mapping between a column name and an existing\ngraph entity, discovered via exact, fuzzy, or embedding-based matching.\n\nRequirements: 2.2" }, "EntityDetail": { "properties": { "name": { "type": "string", "title": "Name" }, "score": { "type": "number", "title": "Score" }, "discovered_by": { "type": "string", "title": "Discovered By" } }, "type": "object", "required": [ "name", "score", "discovered_by" ], "title": "EntityDetail", "description": "Individual entity discovered within a phase (detail-level)." }, "EntitySearchResult": { "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "Unique identifier of the entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the entity" }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type/category of the entity" }, "relevance_score": { "type": "number", "title": "Relevance Score", "description": "Relevance score for the search query" }, "is_connected_to_document": { "type": "boolean", "title": "Is Connected To Document", "description": "Whether this entity is already connected to the current document" }, "connection_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Type", "description": "Type of existing connection to the document, if any" } }, "type": "object", "required": [ "entity_id", "entity_name", "entity_type", "relevance_score", "is_connected_to_document" ], "title": "EntitySearchResult", "description": "A single result from a graph entity search.\n\nRequirements: 7.1" }, "EvalQueryListResponse": { "properties": { "queries": { "items": { "$ref": "#/components/schemas/EvalQuerySummary" }, "type": "array", "title": "Queries" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "queries", "total", "page", "page_size" ], "title": "EvalQueryListResponse", "description": "Response for GET /v1/eval/queries." }, "EvalQuerySummary": { "properties": { "query_id": { "type": "string", "title": "Query Id" }, "timestamp": { "type": "string", "title": "Timestamp" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "question": { "type": "string", "title": "Question" }, "mode_used": { "type": "string", "title": "Mode Used" }, "total_latency_ms": { "type": "number", "title": "Total Latency Ms" }, "success": { "type": "boolean", "title": "Success" }, "entities_resolved": { "type": "integer", "title": "Entities Resolved" }, "entities_requested": { "type": "integer", "title": "Entities Requested" }, "phase_count": { "type": "integer", "title": "Phase Count" }, "has_feedback": { "type": "boolean", "title": "Has Feedback" }, "feedback_rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback Rating" } }, "type": "object", "required": [ "query_id", "timestamp", "session_id", "question", "mode_used", "total_latency_ms", "success", "entities_resolved", "entities_requested", "phase_count", "has_feedback", "feedback_rating" ], "title": "EvalQuerySummary", "description": "Summary of a single query for the list endpoint." }, "EventQueryResult": { "properties": { "events": { "items": { "$ref": "#/components/schemas/GraphEvent" }, "type": "array", "title": "Events", "description": "List of graph events matching the query" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of events matching the query" }, "next_cursor": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Cursor", "description": "Sequence number cursor for the next page; None if no more results" } }, "type": "object", "required": [ "events", "total_count" ], "title": "EventQueryResult", "description": "Paginated result set for event log queries.\n\nContains the matching events, total count, and an optional cursor\nfor fetching the next page.\n\nRequirements: 3.1" }, "EventStoreStats": { "properties": { "total_events": { "type": "integer", "title": "Total Events", "description": "Total number of events in the event store" }, "earliest_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Earliest Timestamp", "description": "Timestamp of the earliest event; None if the store is empty" }, "latest_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest Timestamp", "description": "Timestamp of the latest event; None if the store is empty" } }, "type": "object", "required": [ "total_events" ], "title": "EventStoreStats", "description": "Summary statistics for the event store.\n\nReports the total event count and the timestamp range of stored events.\n\nRequirements: 4.2" }, "ExecuteExplorationRequest": { "properties": { "thread_id": { "type": "string", "title": "Thread Id", "description": "Thread ID for the cell tree" }, "suggestion": { "$ref": "#/components/schemas/GraphExplorationSuggestion", "description": "The exploration suggestion to execute" } }, "type": "object", "required": [ "thread_id", "suggestion" ], "title": "ExecuteExplorationRequest", "description": "Request body for creating a code cell from an exploration suggestion." }, "ExecuteRequest": { "properties": { "cell_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "Cell Ids", "description": "Cell IDs to execute" }, "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for query execution" } }, "type": "object", "required": [ "cell_ids", "session_id" ], "title": "ExecuteRequest" }, "ExecuteResponse": { "properties": { "thread_id": { "type": "string", "title": "Thread Id" }, "results": { "items": { "$ref": "#/components/schemas/ExecuteResultItem" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "thread_id", "results" ], "title": "ExecuteResponse" }, "ExecuteResultItem": { "properties": { "cell_id": { "type": "string", "format": "uuid", "title": "Cell Id" }, "status": { "$ref": "#/components/schemas/CellStatus" }, "outputs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Outputs" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "cell_id", "status" ], "title": "ExecuteResultItem" }, "ExpandKNNCellRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for Neo4j driver access" }, "k": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "K", "description": "Max neighbors per seed node", "default": 10 }, "max_depth": { "type": "integer", "maximum": 3.0, "minimum": 1.0, "title": "Max Depth", "description": "Traversal depth", "default": 1 } }, "type": "object", "required": [ "session_id" ], "title": "ExpandKNNCellRequest", "description": "Request body for the KNN expansion child-cell endpoint." }, "ExtractedMetadata": { "properties": { "suggested_display_name": { "type": "string", "title": "Suggested Display Name" }, "suggested_description": { "type": "string", "title": "Suggested Description" }, "extracted_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extracted Date" }, "extracted_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extracted Version" }, "inferred_topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inferred Topic" }, "filename_segments": { "items": { "type": "string" }, "type": "array", "title": "Filename Segments" } }, "type": "object", "required": [ "suggested_display_name", "suggested_description", "filename_segments" ], "title": "ExtractedMetadata", "description": "Output of the MetadataExtractor." }, "FederatedQueryRequest": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "The requesting user's identifier" }, "tenant_ids": { "items": { "type": "string" }, "type": "array", "title": "Tenant Ids", "description": "Tenant identifiers to query across" }, "query": { "type": "string", "title": "Query", "description": "The Cypher query to execute" }, "params": { "additionalProperties": true, "type": "object", "title": "Params", "description": "Optional query parameters", "default": {} } }, "type": "object", "required": [ "user_id", "tenant_ids", "query" ], "title": "FederatedQueryRequest", "description": "Request body for federated cross-tenant queries." }, "FederatedQueryResult": { "properties": { "results": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Results", "description": "Merged and deduplicated query results from all queried tenants" }, "source_annotations": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Source Annotations", "description": "Mapping of entity_id to source_tenant_id indicating which tenant contributed each entity" }, "tenants_queried": { "items": { "type": "string" }, "type": "array", "title": "Tenants Queried", "description": "List of tenant IDs that were successfully queried" }, "tenants_timed_out": { "items": { "type": "string" }, "type": "array", "title": "Tenants Timed Out", "description": "List of tenant IDs whose queries exceeded the timeout", "default": [] }, "tenants_unavailable": { "items": { "type": "string" }, "type": "array", "title": "Tenants Unavailable", "description": "List of tenant IDs that were unavailable (e.g., deleted tenants excluded from execution)", "default": [] }, "truncated": { "type": "boolean", "title": "Truncated", "description": "True if results are partial due to tenant query timeouts", "default": false }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "description": "Warning messages (e.g., deleted tenants excluded from query)", "default": [] } }, "type": "object", "required": [ "results", "source_annotations", "tenants_queried" ], "title": "FederatedQueryResult", "description": "Result of a cross-tenant federated query.\n\nContains the merged and deduplicated results from multiple tenant\npartitions, with source annotations, timeout/unavailability tracking,\nand optional warnings.\n\nRequirements: 8.4" }, "FeedbackDistribution": { "properties": { "thumbs_up": { "type": "integer", "title": "Thumbs Up" }, "thumbs_down": { "type": "integer", "title": "Thumbs Down" }, "numeric": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Numeric" } }, "type": "object", "required": [ "thumbs_up", "thumbs_down", "numeric" ], "title": "FeedbackDistribution" }, "FeedbackRequest": { "properties": { "query_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Query Index", "description": "Index of the query being rated (default: most recent)" }, "rating": { "enum": [ "thumbs_up", "thumbs_down", 1, 2, 3, 4, 5 ], "title": "Rating", "description": "Rating type: thumbs_up/thumbs_down or 1-5 stars" }, "comment": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Comment", "description": "Optional user comment or feedback text" }, "feedback_type": { "type": "string", "enum": [ "answer_quality", "relevance", "accuracy", "other" ], "title": "Feedback Type", "description": "Category of feedback", "default": "answer_quality" } }, "type": "object", "required": [ "rating" ], "title": "FeedbackRequest", "description": "Request model for user feedback submission." }, "FeedbackResponse": { "properties": { "feedback_id": { "type": "string", "title": "Feedback Id", "description": "Unique identifier for the feedback" }, "session_id": { "type": "string", "title": "Session Id", "description": "Session ID the feedback belongs to" }, "query_index": { "type": "integer", "title": "Query Index", "description": "Index of the rated query" }, "created_at": { "type": "string", "title": "Created At", "description": "ISO timestamp of feedback creation" }, "message": { "type": "string", "title": "Message", "description": "Confirmation message" } }, "type": "object", "required": [ "feedback_id", "session_id", "query_index", "created_at", "message" ], "title": "FeedbackResponse", "description": "Response model for feedback submission." }, "FileMetadata": { "properties": { "file_id": { "type": "string", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "file_size": { "type": "integer", "title": "File Size" }, "file_type": { "type": "string", "title": "File Type" }, "session_id": { "type": "string", "title": "Session Id" }, "upload_timestamp": { "type": "string", "title": "Upload Timestamp" }, "storage_path": { "type": "string", "title": "Storage Path" } }, "type": "object", "required": [ "file_id", "filename", "file_size", "file_type", "session_id", "upload_timestamp", "storage_path" ], "title": "FileMetadata", "description": "Metadata for an uploaded file." }, "GenerateCodeRequest": { "properties": { "query": { "type": "string", "title": "Query" } }, "type": "object", "required": [ "query" ], "title": "GenerateCodeRequest" }, "GraphEvent": { "properties": { "sequence_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sequence Number", "description": "Monotonically increasing sequence number assigned by the EventStore" }, "actor_id": { "type": "string", "title": "Actor Id", "description": "Identifier of the actor (user or system) that performed the mutation" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "ISO 8601 timestamp of when the mutation occurred" }, "mutation_type": { "type": "string", "enum": [ "node_create", "node_update", "edge_create", "edge_update", "edge_close" ], "title": "Mutation Type", "description": "Type of graph mutation performed" }, "affected_entity_id": { "type": "string", "title": "Affected Entity Id", "description": "Identifier of the affected node or relationship" }, "source_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Node Id", "description": "Source node identifier for edge events" }, "target_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Node Id", "description": "Target node identifier for edge events" }, "relationship_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relationship Type", "description": "Relationship type for edge events" }, "before_snapshot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Before Snapshot", "description": "Property snapshot before the mutation" }, "after_snapshot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "After Snapshot", "description": "Property snapshot after the mutation" } }, "type": "object", "required": [ "actor_id", "timestamp", "mutation_type", "affected_entity_id" ], "title": "GraphEvent", "description": "A single immutable record of a graph mutation.\n\nCaptures the actor, timestamp, mutation type, affected entity,\nand optional before/after property snapshots for full audit trails.\n\nRequirements: 1.1\u20131.6, 3.1" }, "GraphExplorationSuggestion": { "properties": { "title": { "type": "string", "title": "Title", "description": "Short title for the suggestion" }, "description": { "type": "string", "title": "Description", "description": "Detailed description of the suggested exploration" }, "code_template": { "type": "string", "title": "Code Template", "description": "Executable code template for the suggestion" }, "related_entities": { "items": { "type": "string" }, "type": "array", "title": "Related Entities", "description": "Entity IDs related to this suggestion" }, "priority": { "type": "integer", "title": "Priority", "description": "Priority ranking (lower is higher priority)" } }, "type": "object", "required": [ "title", "description", "code_template", "related_entities", "priority" ], "title": "GraphExplorationSuggestion", "description": "A graph-guided exploration suggestion for a document.\n\nGenerated by combining document schema with graph connectivity\nto suggest meaningful analyses.\n\nRequirements: 7.1" }, "GraphNeighborhood": { "properties": { "center_entity_id": { "type": "string", "title": "Center Entity Id", "description": "Entity ID at the center of the neighborhood" }, "nodes": { "items": { "$ref": "#/components/schemas/NeighborNode" }, "type": "array", "title": "Nodes", "description": "Neighbor nodes in the subgraph" }, "edges": { "items": { "$ref": "#/components/schemas/NeighborEdge" }, "type": "array", "title": "Edges", "description": "Edges connecting nodes in the subgraph" } }, "type": "object", "required": [ "center_entity_id", "nodes", "edges" ], "title": "GraphNeighborhood", "description": "N-hop subgraph around a center entity.\n\nRequirements: 3.3" }, "GraphSnapshot": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/NodeSnapshot" }, "type": "array", "title": "Nodes", "description": "Nodes active within the temporal window" }, "relationships": { "items": { "$ref": "#/components/schemas/RelationshipSnapshot" }, "type": "array", "title": "Relationships", "description": "Relationships active within the temporal window" }, "truncated": { "type": "boolean", "title": "Truncated", "description": "True if the snapshot was truncated to the node limit", "default": false }, "total_node_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Node Count", "description": "Total number of nodes before truncation; None if not truncated" } }, "type": "object", "required": [ "nodes", "relationships" ], "title": "GraphSnapshot", "description": "A complete graph snapshot at a point in time or over a time range.\n\nContains the nodes and relationships active within the temporal window,\nwith truncation metadata when the node count exceeds the configured limit.\n\nRequirements: 12.3, 12.4, 12.5, 12.6" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HistoryEntry": { "properties": { "timestamp": { "type": "string", "title": "Timestamp" }, "rating": { "type": "number", "title": "Rating" }, "outcome": { "type": "integer", "title": "Outcome" } }, "type": "object", "required": [ "timestamp", "rating", "outcome" ], "title": "HistoryEntry" }, "IngestRequest": { "properties": { "database": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Database" } }, "type": "object", "title": "IngestRequest", "description": "Request model for table-to-KG ingestion." }, "IngestResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "job_id", "status" ], "title": "IngestResponse", "description": "Response model for table-to-KG ingestion." }, "IsolationVerificationResult": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Identifier of the tenant whose isolation was verified" }, "verified": { "type": "boolean", "title": "Verified", "description": "True if no foreign data was found in the tenant partition" }, "foreign_node_count": { "type": "integer", "title": "Foreign Node Count", "description": "Number of nodes from other tenants found in the partition; should be 0 if verified" }, "foreign_relationship_count": { "type": "integer", "title": "Foreign Relationship Count", "description": "Number of relationships from other tenants found in the partition; should be 0 if verified" } }, "type": "object", "required": [ "tenant_id", "verified", "foreign_node_count", "foreign_relationship_count" ], "title": "IsolationVerificationResult", "description": "Result of verifying tenant data isolation.\n\nConfirms whether the tenant partition contains only its own data,\nreporting counts of any foreign nodes or relationships found.\n\nRequirements: 10.5" }, "JobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Unique job identifier" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "Status", "description": "Current job status" }, "progress_percentage": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Progress Percentage", "description": "Job completion percentage" }, "created_at": { "type": "string", "title": "Created At", "description": "Job creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp (ISO 8601)" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Error message if job failed" }, "params": { "additionalProperties": true, "type": "object", "title": "Params", "description": "Job parameters" }, "processed_count": { "type": "integer", "minimum": 0.0, "title": "Processed Count", "description": "Number of publications processed" }, "total_count": { "type": "integer", "minimum": 0.0, "title": "Total Count", "description": "Total publications to process" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage", "description": "Current pipeline stage (e.g., fetching, extraction, kg_pipeline)" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Additional details like node counts, chunk counts, etc." } }, "type": "object", "required": [ "job_id", "status", "progress_percentage", "created_at", "updated_at", "params", "processed_count", "total_count" ], "title": "JobResponse", "description": "Response model for ingestion job status and metadata." }, "KNNExpansionRequest": { "properties": { "query_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Query Index", "description": "Index of previous query to expand from (default: last query)" } }, "type": "object", "title": "KNNExpansionRequest" }, "KNNExpansionResponse": { "properties": { "expanded_results": { "additionalProperties": true, "type": "object", "title": "Expanded Results", "description": "Expanded results containing nodes and links" }, "new_neighbors_count": { "type": "integer", "title": "New Neighbors Count", "description": "Number of new neighbors added" }, "expansion_level": { "type": "integer", "title": "Expansion Level", "description": "Expansion level that was performed" }, "entity_types_added": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Entity Types Added", "description": "Count of entities added by type" } }, "type": "object", "required": [ "expanded_results", "new_neighbors_count", "expansion_level", "entity_types_added" ], "title": "KNNExpansionResponse" }, "KeyInfo": { "properties": { "key_id": { "type": "string", "title": "Key Id" }, "last_8": { "type": "string", "title": "Last 8" }, "created_at": { "type": "string", "title": "Created At" }, "expires_at": { "type": "string", "title": "Expires At" }, "role": { "type": "string", "title": "Role" }, "label": { "type": "string", "title": "Label", "default": "" } }, "type": "object", "required": [ "key_id", "last_8", "created_at", "expires_at", "role" ], "title": "KeyInfo" }, "Keyframe": { "properties": { "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO 8601 UTC timestamp of this keyframe" }, "node_count": { "type": "integer", "title": "Node Count", "description": "Total number of nodes visible at this timestamp" }, "relationship_count": { "type": "integer", "title": "Relationship Count", "description": "Total number of relationships visible at this timestamp" }, "nodes_added": { "type": "integer", "title": "Nodes Added", "description": "Number of nodes added since the previous keyframe", "default": 0 }, "nodes_removed": { "type": "integer", "title": "Nodes Removed", "description": "Number of nodes removed since the previous keyframe", "default": 0 }, "relationships_added": { "type": "integer", "title": "Relationships Added", "description": "Number of relationships added since the previous keyframe", "default": 0 }, "relationships_removed": { "type": "integer", "title": "Relationships Removed", "description": "Number of relationships removed since the previous keyframe", "default": 0 }, "contradictions_detected": { "items": { "$ref": "#/components/schemas/ContradictionEvent" }, "type": "array", "title": "Contradictions Detected", "description": "Contradiction detection events within this keyframe interval", "default": [] }, "contradictions_resolved": { "items": { "$ref": "#/components/schemas/ResolutionEvent" }, "type": "array", "title": "Contradictions Resolved", "description": "Contradiction resolution events within this keyframe interval", "default": [] } }, "type": "object", "required": [ "timestamp", "node_count", "relationship_count" ], "title": "Keyframe", "description": "A single animation keyframe representing graph state at a timestamp.\n\nContains absolute counts, deltas since the previous keyframe, and any\ncontradiction detection or resolution events within the interval.\n\nRequirements: 13.1, 13.2, 13.3" }, "LeaderboardEntry": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "rating": { "type": "number", "title": "Rating" }, "rating_deviation": { "type": "number", "title": "Rating Deviation" }, "confidence_interval": { "$ref": "#/components/schemas/ConfidenceInterval" }, "games_played": { "type": "integer", "title": "Games Played" }, "wins": { "type": "integer", "title": "Wins" }, "losses": { "type": "integer", "title": "Losses" }, "win_rate": { "type": "number", "title": "Win Rate" }, "sufficient_data": { "type": "boolean", "title": "Sufficient Data" }, "last_updated": { "type": "string", "title": "Last Updated" } }, "type": "object", "required": [ "agent_id", "rating", "rating_deviation", "confidence_interval", "games_played", "wins", "losses", "win_rate", "sufficient_data", "last_updated" ], "title": "LeaderboardEntry" }, "LineageEdge": { "properties": { "edge_id": { "type": "string", "title": "Edge Id" }, "parent_id": { "type": "string", "title": "Parent Id" }, "child_id": { "type": "string", "title": "Child Id" }, "session_id": { "type": "string", "title": "Session Id" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "edge_id", "parent_id", "child_id", "session_id", "created_at" ], "title": "LineageEdge", "description": "A single parent\u2192child relationship." }, "LineageEdgeRequest": { "properties": { "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id" }, "child_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Child Id" } }, "type": "object", "title": "LineageEdgeRequest", "description": "Request body for adding a lineage edge." }, "LineageTree": { "properties": { "nodes": { "items": { "type": "string" }, "type": "array", "title": "Nodes" }, "edges": { "items": { "$ref": "#/components/schemas/LineageEdge" }, "type": "array", "title": "Edges" } }, "type": "object", "required": [ "nodes", "edges" ], "title": "LineageTree", "description": "Full lineage graph for a session." }, "ListKeysResponse": { "properties": { "keys": { "items": { "$ref": "#/components/schemas/KeyInfo" }, "type": "array", "title": "Keys" } }, "type": "object", "required": [ "keys" ], "title": "ListKeysResponse" }, "MigrateRequest": { "properties": { "team_name": { "type": "string", "title": "Team Name", "description": "Team name whose data to migrate" } }, "type": "object", "required": [ "team_name" ], "title": "MigrateRequest", "description": "Request body for triggering tenant data migration." }, "MigrationResult": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Identifier of the tenant whose data was migrated" }, "nodes_migrated": { "type": "integer", "title": "Nodes Migrated", "description": "Number of nodes successfully copied into the tenant partition" }, "relationships_migrated": { "type": "integer", "title": "Relationships Migrated", "description": "Number of relationships successfully copied into the tenant partition" }, "nodes_skipped": { "type": "integer", "title": "Nodes Skipped", "description": "Number of nodes skipped due to missing team attribution" }, "shared_entity_ids": { "items": { "type": "string" }, "type": "array", "title": "Shared Entity Ids", "description": "Entity IDs with provenance chains from multiple teams, copied into each relevant tenant partition" }, "isolation_verified": { "type": "boolean", "title": "Isolation Verified", "description": "Whether post-migration isolation verification confirmed no cross-tenant data leakage" } }, "type": "object", "required": [ "tenant_id", "nodes_migrated", "relationships_migrated", "nodes_skipped", "shared_entity_ids", "isolation_verified" ], "title": "MigrationResult", "description": "Result of migrating a tenant's data into an isolated partition.\n\nReports the counts of migrated and skipped nodes and relationships,\nidentifiers of shared entities copied to multiple tenant partitions,\nand whether post-migration isolation verification passed.\n\nRequirements: 10.5, 10.7" }, "ModelOption": { "properties": { "value": { "type": "string", "title": "Value" }, "label": { "type": "string", "title": "Label" }, "provider": { "type": "string", "title": "Provider", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "vision_capable": { "type": "boolean", "title": "Vision Capable", "default": false } }, "type": "object", "required": [ "value", "label" ], "title": "ModelOption", "description": "A selectable model option." }, "MultiDocumentOverlay": { "properties": { "file_ids": { "items": { "type": "string" }, "type": "array", "title": "File Ids", "description": "List of document file IDs in the overlay" }, "shared_entities": { "items": { "$ref": "#/components/schemas/SharedEntity" }, "type": "array", "title": "Shared Entities", "description": "Entities shared across the selected documents" }, "shared_edges": { "items": { "$ref": "#/components/schemas/NeighborEdge" }, "type": "array", "title": "Shared Edges", "description": "Edges connecting shared entities" }, "is_disjoint": { "type": "boolean", "title": "Is Disjoint", "description": "True if no shared graph connections exist between the documents" }, "linking_suggestions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EntityCandidate" }, "type": "array" }, { "type": "null" } ], "title": "Linking Suggestions", "description": "Suggested linking entities when documents are disjoint" } }, "type": "object", "required": [ "file_ids", "shared_entities", "shared_edges", "is_disjoint" ], "title": "MultiDocumentOverlay", "description": "Graph overlay showing shared entities and edges across multiple documents.\n\nRequirements: 9.1" }, "NeighborEdge": { "properties": { "source_id": { "type": "string", "title": "Source Id", "description": "Entity ID of the edge source" }, "target_id": { "type": "string", "title": "Target Id", "description": "Entity ID of the edge target" }, "relationship_type": { "type": "string", "title": "Relationship Type", "description": "Type of the relationship" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence", "description": "Confidence score of the edge, if available" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional edge metadata" } }, "type": "object", "required": [ "source_id", "target_id", "relationship_type" ], "title": "NeighborEdge", "description": "An edge in an entity's graph neighborhood.\n\nRequirements: 3.3" }, "NeighborNode": { "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "Unique identifier of the neighbor entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the neighbor entity" }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type/category of the neighbor entity" } }, "type": "object", "required": [ "entity_id", "entity_name", "entity_type" ], "title": "NeighborNode", "description": "A node in an entity's graph neighborhood.\n\nRequirements: 3.3" }, "NodeSnapshot": { "properties": { "node_id": { "type": "string", "title": "Node Id", "description": "Unique identifier of the node" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels", "description": "Neo4j labels attached to the node" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name of the node, if available" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Node type (e.g., 'Gene', 'Protein', 'Disease')" }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence Score", "description": "Confidence score (0.0\u20131.0) of the node, if applicable" }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From", "description": "ISO 8601 UTC timestamp when the node became valid" }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid To", "description": "ISO 8601 UTC timestamp when the node was superseded; None if currently valid" } }, "type": "object", "required": [ "node_id", "labels" ], "title": "NodeSnapshot", "description": "A node as it appears in a temporal graph snapshot.\n\nContains display-relevant properties for frontend rendering: identifier,\nlabels, name, type, confidence score, and temporal validity window.\n\nRequirements: 12.3" }, "OrgThreadSummary": { "properties": { "thread_id": { "type": "string", "title": "Thread Id" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "root_cell_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Cell Id" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "permission": { "type": "string", "title": "Permission" } }, "type": "object", "required": [ "thread_id", "owner_id", "root_cell_id", "created_at", "permission" ], "title": "OrgThreadSummary" }, "OverlapResult": { "properties": { "team_pair_matrix": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Team Pair Matrix", "description": "Team-pair overlap entries: [{team_a, team_b, jaccard, overlap_count}]" }, "unique_contributions": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Unique Contributions", "description": "Per-team count of relationships where only that team has contributed a provenance chain" } }, "type": "object", "required": [ "team_pair_matrix", "unique_contributions" ], "title": "OverlapResult", "description": "Knowledge overlap and unique contribution metrics across teams.\n\nContains a team-pair matrix with Jaccard similarity coefficients and\noverlap counts, plus per-team unique contribution counts.\n\nRequirements: 10.1, 10.2" }, "OverlayRequest": { "properties": { "file_ids": { "items": { "type": "string" }, "type": "array", "title": "File Ids", "description": "List of document file IDs to overlay (minimum 2)" } }, "type": "object", "required": [ "file_ids" ], "title": "OverlayRequest", "description": "Request body for computing a multi-document overlay." }, "PermissionRequest": { "properties": { "permission_level": { "type": "string", "title": "Permission Level", "description": "Permission level: 'read', 'write', or 'admin'" } }, "type": "object", "required": [ "permission_level" ], "title": "PermissionRequest", "description": "Request body for granting/revoking tenant permissions." }, "PhaseBreakdownEntry": { "properties": { "phase_name": { "type": "string", "title": "Phase Name" }, "duration_ms": { "type": "integer", "title": "Duration Ms" }, "tool_call_count": { "type": "integer", "title": "Tool Call Count" }, "entities_discovered_count": { "type": "integer", "title": "Entities Discovered Count" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "phase_name", "duration_ms", "tool_call_count", "entities_discovered_count", "status" ], "title": "PhaseBreakdownEntry", "description": "Summary of a single execution phase for list-level display." }, "PhaseDetail": { "properties": { "phase_name": { "type": "string", "title": "Phase Name" }, "duration_ms": { "type": "integer", "title": "Duration Ms" }, "tool_calls": { "items": { "$ref": "#/components/schemas/ToolCallDetail" }, "type": "array", "title": "Tool Calls", "default": [] }, "entities_discovered": { "items": { "$ref": "#/components/schemas/EntityDetail" }, "type": "array", "title": "Entities Discovered", "default": [] }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "phase_name", "duration_ms", "status" ], "title": "PhaseDetail", "description": "Full phase detail including tool calls and entities (for single-query endpoint)." }, "ProvenanceEvent": { "properties": { "event_id": { "type": "string", "title": "Event Id", "description": "Unique identifier for the provenance event" }, "file_id": { "type": "string", "title": "File Id", "description": "Identifier of the associated document" }, "actor": { "type": "string", "title": "Actor", "description": "User or system identifier that performed the action" }, "action_type": { "type": "string", "title": "Action Type", "description": "Type of action: 'mapping_confirmed', 'annotation_created', 'enrichment_completed', etc." }, "affected_entities": { "items": { "type": "string" }, "type": "array", "title": "Affected Entities", "description": "List of entity IDs affected by this action" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp when the event occurred" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional context for the event" } }, "type": "object", "required": [ "event_id", "file_id", "actor", "action_type", "affected_entities", "timestamp" ], "title": "ProvenanceEvent", "description": "A provenance event recording a document-graph interaction.\n\nRequirements: 8.1" }, "ProviderOption": { "properties": { "value": { "type": "string", "title": "Value" }, "label": { "type": "string", "title": "Label" }, "description": { "type": "string", "title": "Description", "default": "" } }, "type": "object", "required": [ "value", "label" ], "title": "ProviderOption", "description": "An LLM provider (bedrock, sagemaker, local)." }, "QueryExecutionRecord": { "properties": { "query_id": { "type": "string", "title": "Query Id" }, "timestamp": { "type": "string", "title": "Timestamp" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "query_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Query Index" }, "question": { "type": "string", "title": "Question" }, "mode_requested": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode Requested" }, "mode_used": { "type": "string", "title": "Mode Used" }, "total_latency_ms": { "type": "number", "title": "Total Latency Ms" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "entities_requested": { "type": "integer", "title": "Entities Requested", "default": 0 }, "entities_resolved": { "type": "integer", "title": "Entities Resolved", "default": 0 }, "hop_depth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Hop Depth" }, "cache_hit": { "type": "boolean", "title": "Cache Hit", "default": false }, "community_summaries_retrieved": { "type": "integer", "title": "Community Summaries Retrieved", "default": 0 }, "phase_breakdown": { "items": { "$ref": "#/components/schemas/PhaseBreakdownEntry" }, "type": "array", "title": "Phase Breakdown", "default": [] }, "phase_details": { "items": { "$ref": "#/components/schemas/PhaseDetail" }, "type": "array", "title": "Phase Details", "default": [] }, "strategy_summary": { "items": { "$ref": "#/components/schemas/StrategySummaryEntry" }, "type": "array", "title": "Strategy Summary", "default": [] }, "has_follow_up": { "type": "boolean", "title": "Has Follow Up", "default": false } }, "type": "object", "required": [ "query_id", "timestamp", "session_id", "question", "mode_requested", "mode_used", "total_latency_ms", "success" ], "title": "QueryExecutionRecord", "description": "Central record joining metrics, execution trace, and feedback linkage." }, "QueryRequest": { "properties": { "question": { "type": "string", "minLength": 3, "title": "Question", "description": "Natural language question" }, "use_refrag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Refrag", "description": "Optional override for REFRAG processing on a per-request basis" }, "knn_expansion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Knn Expansion", "description": "Optional k-nearest neighbor expansion level (1, 2, 3, etc.) to perform after initial query" }, "llm_context_limit": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ], "title": "Llm Context Limit", "description": "Optional limit for LLM context. If 0 < x < 1, represents percentage. If x >= 1, represents count." }, "stream": { "type": "boolean", "title": "Stream", "description": "When True, return response as Server-Sent Events stream instead of JSON.", "default": false }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode", "description": "Query mode: 'naive', 'local', 'global', 'hybrid', 'mix', or 'bypass'. Auto-classified if omitted." }, "mix_weights": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Mix Weights", "description": "Weight ratios for mix mode. Keys: 'vector', 'graph'. Values must sum to 1.0. Example: {'vector': 0.3, 'graph': 0.7}" }, "hop_depth": { "anyOf": [ { "type": "integer", "maximum": 3.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Hop Depth", "description": "Number of relationship hops to traverse (1-3). Default: 1. Higher values find more distant connections.", "default": 1 }, "search_depth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Depth", "description": "Search depth: 'fast' (discovery only), 'balanced' (default), or 'deep' (full expansion + cypher).", "default": "balanced" } }, "type": "object", "required": [ "question" ], "title": "QueryRequest" }, "QueryResponse": { "properties": { "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer" }, "sources": { "items": {}, "type": "array", "title": "Sources", "description": "Sources with sentence-level evidence. Each entry: {source: str, evidence: [{sentence, chunk_id, char_span}]}" }, "detailed_results": { "anyOf": [ { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" } ], "title": "Detailed Results" }, "graph_analytics": { "additionalProperties": true, "type": "object", "title": "Graph Analytics" }, "refrag_stats": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Refrag Stats" }, "table_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Table Data" }, "retrieval_process": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "additionalProperties": true, "type": "object" } ], "title": "Retrieval Process" } }, "type": "object", "required": [ "answer" ], "title": "QueryResponse" }, "RatingRange": { "properties": { "min": { "type": "number", "title": "Min" }, "max": { "type": "number", "title": "Max" }, "span": { "type": "number", "title": "Span" } }, "type": "object", "required": [ "min", "max", "span" ], "title": "RatingRange" }, "RegisterTenantRequest": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Unique identifier for the new tenant" }, "isolation_strategy": { "type": "string", "title": "Isolation Strategy", "description": "Isolation strategy: 'database' or 'subgraph'" } }, "type": "object", "required": [ "tenant_id", "isolation_strategy" ], "title": "RegisterTenantRequest", "description": "Request body for tenant registration." }, "RejectMappingRequest": { "properties": { "column_name": { "type": "string", "title": "Column Name", "description": "Name of the column" }, "entity_id": { "type": "string", "title": "Entity Id", "description": "Identifier of the rejected entity" } }, "type": "object", "required": [ "column_name", "entity_id" ], "title": "RejectMappingRequest", "description": "Request body for rejecting a column-to-entity mapping." }, "RejectRequest": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the rejecting user" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Optional reason for rejection" } }, "type": "object", "required": [ "user_id" ], "title": "RejectRequest", "description": "Request body for rejecting a candidate." }, "RelationshipSnapshot": { "properties": { "relationship_id": { "type": "string", "title": "Relationship Id", "description": "Unique identifier of the relationship" }, "source_node_id": { "type": "string", "title": "Source Node Id", "description": "Identifier of the source node" }, "target_node_id": { "type": "string", "title": "Target Node Id", "description": "Identifier of the target node" }, "relationship_type": { "type": "string", "title": "Relationship Type", "description": "Type of the relationship (e.g., 'UPREGULATES', 'CORRELATED_WITH')" }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence Score", "description": "Confidence score (0.0\u20131.0) of the relationship, if applicable" }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From", "description": "ISO 8601 UTC timestamp when the relationship became valid" }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid To", "description": "ISO 8601 UTC timestamp when the relationship was superseded; None if currently valid" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type", "description": "Source type of the relationship (e.g., 'statistical_analysis', 'llm')" }, "contradicting_relationship_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contradicting Relationship Id", "description": "Identifier of the contradicting relationship, if a CONTRADICTS edge exists" }, "contradiction_detected_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contradiction Detected At", "description": "ISO 8601 UTC timestamp when the contradiction was detected" } }, "type": "object", "required": [ "relationship_id", "source_node_id", "target_node_id", "relationship_type" ], "title": "RelationshipSnapshot", "description": "A relationship as it appears in a temporal graph snapshot.\n\nContains display-relevant properties including contradiction metadata\nwhen the relationship has a CONTRADICTS edge.\n\nRequirements: 12.4, 12.5" }, "RenameColumnRequest": { "properties": { "old_name": { "type": "string", "title": "Old Name" }, "new_name": { "type": "string", "title": "New Name" } }, "type": "object", "required": [ "old_name", "new_name" ], "title": "RenameColumnRequest", "description": "Request model for renaming a column in an uploaded file." }, "ReplayRequest": { "properties": { "target_timestamp": { "type": "string", "format": "date-time", "title": "Target Timestamp", "description": "Target timestamp to replay events up to" } }, "type": "object", "required": [ "target_timestamp" ], "title": "ReplayRequest", "description": "Request body for the replay endpoint." }, "ReplayResult": { "properties": { "total_events": { "type": "integer", "title": "Total Events", "description": "Total number of events considered for replay" }, "events_replayed": { "type": "integer", "title": "Events Replayed", "description": "Number of events successfully replayed" }, "events_skipped": { "type": "integer", "title": "Events Skipped", "description": "Number of events skipped during replay" }, "node_count": { "type": "integer", "title": "Node Count", "description": "Number of nodes in the reconstructed graph state" }, "relationship_count": { "type": "integer", "title": "Relationship Count", "description": "Number of relationships in the reconstructed graph state" } }, "type": "object", "required": [ "total_events", "events_replayed", "events_skipped", "node_count", "relationship_count" ], "title": "ReplayResult", "description": "Summary of an event replay operation.\n\nReports the total events considered, how many were replayed vs skipped,\nand the resulting graph state counts.\n\nRequirements: 2.6" }, "ResolutionEvent": { "properties": { "winning_relationship_id": { "type": "string", "title": "Winning Relationship Id", "description": "Identifier of the relationship that won the contradiction resolution" }, "resolved_at": { "type": "string", "title": "Resolved At", "description": "ISO 8601 UTC timestamp when the contradiction was resolved" } }, "type": "object", "required": [ "winning_relationship_id", "resolved_at" ], "title": "ResolutionEvent", "description": "A contradiction resolution event within a keyframe interval.\n\nRecords the winning relationship and the resolution timestamp.\n\nRequirements: 13.3" }, "RetryCellRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session ID for query execution" }, "search_depth": { "type": "string", "title": "Search Depth", "description": "Search depth: 'fast', 'balanced', or 'deep'", "default": "balanced" } }, "type": "object", "required": [ "session_id" ], "title": "RetryCellRequest" }, "SampleQueries": { "properties": { "best_rated": { "items": { "$ref": "#/components/schemas/SampleQuery" }, "type": "array", "title": "Best Rated" }, "worst_rated": { "items": { "$ref": "#/components/schemas/SampleQuery" }, "type": "array", "title": "Worst Rated" } }, "type": "object", "required": [ "best_rated", "worst_rated" ], "title": "SampleQueries" }, "SampleQuery": { "properties": { "question": { "type": "string", "title": "Question" }, "answer": { "type": "string", "title": "Answer" }, "timestamp": { "type": "string", "title": "Timestamp" } }, "type": "object", "required": [ "question", "answer", "timestamp" ], "title": "SampleQuery" }, "ScanRequest": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id", "description": "Identifier of the dataset to scan" }, "column_names": { "items": { "type": "string" }, "type": "array", "title": "Column Names", "description": "List of column names to include in the scan" } }, "type": "object", "required": [ "dataset_id", "column_names" ], "title": "ScanRequest", "description": "Request body for triggering a dataset scan." }, "SessionCreateRequest": { "properties": { "llm_service": { "type": "string", "title": "Llm Service", "description": "LLM backend identifier" }, "database_name": { "type": "string", "title": "Database Name", "description": "Database identifier or connection string" }, "database_type": { "type": "string", "title": "Database Type", "description": "Database type, e.g. 'neo4j'" }, "agent_type": { "type": "string", "title": "Agent Type", "description": "Agent flavour selection", "default": "Standard" }, "model_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Id", "description": "Bedrock model ID override (e.g. 'us.meta.llama3-1-8b-instruct-v1:0')" }, "use_refrag": { "type": "boolean", "title": "Use Refrag", "description": "Enable Meta REFRAG compressed retrieval", "default": false }, "demo_mode": { "type": "boolean", "title": "Demo Mode", "description": "Persist results for demo or caching", "default": false }, "filter_nodes": { "type": "boolean", "title": "Filter Nodes", "description": "Filter non-biological nodes in visualizations", "default": false }, "connection_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Connection Details", "description": "Database connection details for Neo4j" } }, "type": "object", "required": [ "llm_service", "database_name", "database_type" ], "title": "SessionCreateRequest" }, "SessionCreateResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "created_at": { "type": "string", "title": "Created At" }, "config": { "additionalProperties": true, "type": "object", "title": "Config" } }, "type": "object", "required": [ "session_id", "created_at", "config" ], "title": "SessionCreateResponse" }, "SessionSummaryResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "created_at": { "type": "string", "title": "Created At" }, "config": { "additionalProperties": true, "type": "object", "title": "Config" }, "history": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "History" } }, "type": "object", "required": [ "session_id", "created_at", "config", "history" ], "title": "SessionSummaryResponse" }, "ShareToOrgRequest": { "properties": { "org_id": { "type": "string", "minLength": 1, "title": "Org Id", "description": "Organization ID to share with" }, "owner_id": { "type": "string", "minLength": 1, "title": "Owner Id", "description": "User ID of the person sharing" }, "permission": { "type": "string", "title": "Permission", "description": "Permission for org members: read (locked) or write (editable)", "default": "read" } }, "type": "object", "required": [ "org_id", "owner_id" ], "title": "ShareToOrgRequest" }, "SharedEntity": { "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "Unique identifier of the shared entity" }, "entity_name": { "type": "string", "title": "Entity Name", "description": "Display name of the shared entity" }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type/category of the shared entity" }, "contributing_documents": { "items": { "type": "string" }, "type": "array", "title": "Contributing Documents", "description": "List of file IDs that connect to this entity" }, "overlap_count": { "type": "integer", "title": "Overlap Count", "description": "Number of documents that share this entity" } }, "type": "object", "required": [ "entity_id", "entity_name", "entity_type", "contributing_documents", "overlap_count" ], "title": "SharedEntity", "description": "An entity shared across multiple documents in a multi-document overlay.\n\nRequirements: 9.1" }, "Statistics": { "properties": { "total_agents": { "type": "integer", "title": "Total Agents" }, "total_games": { "type": "integer", "title": "Total Games" }, "average_rating": { "type": "number", "title": "Average Rating" } }, "type": "object", "required": [ "total_agents", "total_games", "average_rating" ], "title": "Statistics" }, "StatisticsResponse": { "properties": { "statistics": { "$ref": "#/components/schemas/Statistics" }, "leaderboard": { "items": { "$ref": "#/components/schemas/LeaderboardEntry" }, "type": "array", "title": "Leaderboard" } }, "type": "object", "required": [ "statistics", "leaderboard" ], "title": "StatisticsResponse" }, "StrategySummaryEntry": { "properties": { "tool_name": { "type": "string", "title": "Tool Name" }, "invocation_count": { "type": "integer", "title": "Invocation Count" }, "total_results_returned": { "type": "integer", "title": "Total Results Returned" }, "avg_duration_ms": { "type": "number", "title": "Avg Duration Ms" } }, "type": "object", "required": [ "tool_name", "invocation_count", "total_results_returned", "avg_duration_ms" ], "title": "StrategySummaryEntry", "description": "Aggregated stats for a single tool/strategy across all phases." }, "TeamComparisonResult": { "properties": { "team_a": { "type": "string", "title": "Team A", "description": "Name of the first team in the comparison" }, "team_b": { "type": "string", "title": "Team B", "description": "Name of the second team in the comparison" }, "communities_a": { "items": { "$ref": "#/components/schemas/TeamScopedCommunity" }, "type": "array", "title": "Communities A", "description": "Communities detected in team A's contributed subgraph" }, "communities_b": { "items": { "$ref": "#/components/schemas/TeamScopedCommunity" }, "type": "array", "title": "Communities B", "description": "Communities detected in team B's contributed subgraph" }, "shared_entity_ids": { "items": { "type": "string" }, "type": "array", "title": "Shared Entity Ids", "description": "Entity IDs that appear in both teams' subgraphs" }, "overlapping_communities": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Overlapping Communities", "description": "Overlapping community pairs with Jaccard similarity: [{community_a_id, community_b_id, jaccard}]" } }, "type": "object", "required": [ "team_a", "team_b", "communities_a", "communities_b", "shared_entity_ids", "overlapping_communities" ], "title": "TeamComparisonResult", "description": "Comparison of community structures between two teams.\n\nContains the communities detected for each team, shared entity\nidentifiers, and overlapping communities with Jaccard similarity.\n\nRequirements: 3.4" }, "TeamScopedCommunity": { "properties": { "community_id": { "type": "integer", "title": "Community Id", "description": "Unique identifier for this community within the detection run" }, "entity_ids": { "items": { "type": "string" }, "type": "array", "title": "Entity Ids", "description": "Identifiers of entities belonging to this community" }, "entity_names": { "items": { "type": "string" }, "type": "array", "title": "Entity Names", "description": "Display names of entities belonging to this community" }, "size": { "type": "integer", "title": "Size", "description": "Number of entities in this community" }, "team_name": { "type": "string", "title": "Team Name", "description": "Name of the team whose contributed subgraph was used for detection" }, "time_range_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Range Start", "description": "ISO 8601 UTC timestamp of the start of the detection time range; None if not time-filtered" }, "time_range_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Range End", "description": "ISO 8601 UTC timestamp of the end of the detection time range; None if not time-filtered" } }, "type": "object", "required": [ "community_id", "entity_ids", "entity_names", "size", "team_name" ], "title": "TeamScopedCommunity", "description": "A community detected within a team's contributed subgraph.\n\nRepresents a cluster of densely connected entity nodes identified by\nLouvain community detection on a subgraph filtered by provenance chain\nlinks to User_Context_Nodes belonging to a specific team.\n\nRequirements: 3.4" }, "TeamSummary": { "properties": { "team": { "type": "string", "title": "Team", "description": "Team identifier" }, "discovery_count": { "type": "integer", "title": "Discovery Count", "description": "Total number of relationships this team discovered first" }, "mean_confirmation_latency_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Confirmation Latency Hours", "description": "Mean confirmation latency in hours for relationships this team discovered; None if no multi-team relationships" }, "unique_contribution_count": { "type": "integer", "title": "Unique Contribution Count", "description": "Number of relationships where only this team has contributed a provenance chain" }, "top_collaborators": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Top Collaborators", "description": "Top collaborating teams ranked by Jaccard similarity: [{team, jaccard}]" } }, "type": "object", "required": [ "team", "discovery_count", "unique_contribution_count", "top_collaborators" ], "title": "TeamSummary", "description": "Aggregated diffusion metrics summary for a single team.\n\nCombines discovery count, mean confirmation latency, unique contribution\ncount, and top collaborating teams ranked by Jaccard similarity.\n\nRequirements: 8.1, 8.2, 9.1, 9.2, 9.3, 10.1, 10.2" }, "TemporalBounds": { "properties": { "earliest_valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Earliest Valid From", "description": "ISO 8601 UTC timestamp of the earliest valid_from across all nodes and relationships; None if graph is empty" }, "latest_valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Valid From", "description": "ISO 8601 UTC timestamp of the latest valid_from across all nodes and relationships; None if graph is empty" } }, "type": "object", "title": "TemporalBounds", "description": "Temporal bounds of the entire Context_Graph.\n\nReports the earliest and latest valid_from timestamps across all nodes\nand relationships, enabling the frontend time slider to set its range.\n\nRequirements: 14.1" }, "TemporalCommunity": { "properties": { "community_id": { "type": "integer", "title": "Community Id", "description": "Unique identifier for this community within the detection run" }, "entity_ids": { "items": { "type": "string" }, "type": "array", "title": "Entity Ids", "description": "Identifiers of entities belonging to this community" }, "entity_names": { "items": { "type": "string" }, "type": "array", "title": "Entity Names", "description": "Display names of entities belonging to this community" }, "size": { "type": "integer", "title": "Size", "description": "Number of entities in this community" }, "time_range_start": { "type": "string", "title": "Time Range Start", "description": "ISO 8601 UTC timestamp of the start of the detection time range" }, "time_range_end": { "type": "string", "title": "Time Range End", "description": "ISO 8601 UTC timestamp of the end of the detection time range" }, "detection_timestamp": { "type": "string", "title": "Detection Timestamp", "description": "ISO 8601 UTC timestamp when the community was detected" } }, "type": "object", "required": [ "community_id", "entity_ids", "entity_names", "size", "time_range_start", "time_range_end", "detection_timestamp" ], "title": "TemporalCommunity", "description": "A community detected within a specific temporal window.\n\nRepresents a cluster of densely connected entity nodes identified by\nLouvain community detection on a time-filtered subgraph, carrying the\ntime range used for detection and the detection timestamp.\n\nRequirements: 1.4, 5.1" }, "TenantRecord": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Unique identifier for this tenant" }, "isolation_strategy": { "type": "string", "enum": [ "database", "subgraph" ], "title": "Isolation Strategy", "description": "Isolation strategy: 'database' for separate Neo4j databases, 'subgraph' for label-prefix partitioning" }, "status": { "type": "string", "enum": [ "active", "suspended", "deleted" ], "title": "Status", "description": "Current lifecycle status of the tenant" }, "created_at": { "type": "string", "title": "Created At", "description": "ISO 8601 UTC timestamp when the tenant was registered" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "ISO 8601 UTC timestamp of the last status change; None if never updated" } }, "type": "object", "required": [ "tenant_id", "isolation_strategy", "status", "created_at" ], "title": "TenantRecord", "description": "A registered tenant with its isolation configuration and lifecycle status.\n\nRepresents an organizational unit (typically a team) that owns a logically\nor physically isolated portion of the Context_Graph, tracking the chosen\nisolation strategy and current lifecycle status.\n\nRequirements: 6.1" }, "ToolCallDetail": { "properties": { "tool_name": { "type": "string", "title": "Tool Name" }, "duration_ms": { "type": "integer", "title": "Duration Ms" }, "result_count": { "type": "integer", "title": "Result Count" }, "found": { "type": "boolean", "title": "Found" } }, "type": "object", "required": [ "tool_name", "duration_ms", "result_count", "found" ], "title": "ToolCallDetail", "description": "Individual tool call within a phase (detail-level)." }, "TrendMetrics": { "properties": { "convergence_score": { "type": "number", "title": "Convergence Score" }, "stability_percentage": { "type": "number", "title": "Stability Percentage" }, "trend_direction": { "type": "number", "title": "Trend Direction" }, "rating_range": { "$ref": "#/components/schemas/RatingRange" } }, "type": "object", "required": [ "convergence_score", "stability_percentage", "trend_direction", "rating_range" ], "title": "TrendMetrics" }, "TrendsResponse": { "properties": { "trends": { "items": { "$ref": "#/components/schemas/AgentTrend" }, "type": "array", "title": "Trends" } }, "type": "object", "required": [ "trends" ], "title": "TrendsResponse" }, "UpdatePermissionRequest": { "properties": { "permission": { "type": "string", "title": "Permission", "description": "New permission level: read or write" }, "user_id": { "type": "string", "title": "User Id", "description": "Requesting user ID (must be owner)" } }, "type": "object", "required": [ "permission", "user_id" ], "title": "UpdatePermissionRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WorkflowProgress": { "properties": { "workflow_id": { "type": "string", "title": "Workflow Id", "description": "Unique identifier for the workflow run" }, "steps": { "items": { "$ref": "#/components/schemas/WorkflowStepStatus" }, "type": "array", "title": "Steps", "description": "Status of each workflow step" }, "overall_status": { "type": "string", "title": "Overall Status", "description": "Overall workflow status: 'running', 'completed', or 'partial_failure'" } }, "type": "object", "required": [ "workflow_id", "steps", "overall_status" ], "title": "WorkflowProgress", "description": "Progress report for a running enrichment workflow.\n\nRequirements: 6.2" }, "WorkflowStepStatus": { "properties": { "step_name": { "type": "string", "title": "Step Name", "description": "Name of the workflow step" }, "status": { "type": "string", "title": "Status", "description": "Current status: 'pending', 'running', 'completed', or 'failed'" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Timestamp when the step started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Timestamp when the step completed" } }, "type": "object", "required": [ "step_name", "status" ], "title": "WorkflowStepStatus", "description": "Current status of a single workflow step.\n\nRequirements: 6.2" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }