{ "openapi": "3.1.0", "info": { "title": "Cognee API", "description": "Cognee API with Bearer token and Cookie auth", "version": "1.0.0" }, "paths": { "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Login", "description": "Login \u2014 POST /api/v1/auth/login.", "operationId": "login_api_v1_auth_login_post", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_login_api_v1_auth_login_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Logout", "description": "Logout \u2014 POST /api/v1/auth/logout.", "operationId": "logout_api_v1_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "Get Me", "description": "Get me \u2014 GET /api/v1/auth/me.", "operationId": "get_me_api_v1_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/auth/register": { "post": { "tags": [ "auth" ], "summary": "Register:Register", "operationId": "register_register_api_v1_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" }, "examples": { "REGISTER_USER_ALREADY_EXISTS": { "summary": "A user with this email already exists.", "value": { "detail": "REGISTER_USER_ALREADY_EXISTS" } }, "REGISTER_INVALID_PASSWORD": { "summary": "Password validation failed.", "value": { "detail": { "code": "REGISTER_INVALID_PASSWORD", "reason": "Password should beat least 3 characters" } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "auth" ], "summary": "Reset:Forgot Password", "operationId": "reset_forgot_password_api_v1_auth_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_reset_forgot_password_api_v1_auth_forgot_password_post" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/reset-password": { "post": { "tags": [ "auth" ], "summary": "Reset:Reset Password", "operationId": "reset_reset_password_api_v1_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_reset_reset_password_api_v1_auth_reset_password_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" }, "examples": { "RESET_PASSWORD_BAD_TOKEN": { "summary": "Bad or expired token.", "value": { "detail": "RESET_PASSWORD_BAD_TOKEN" } }, "RESET_PASSWORD_INVALID_PASSWORD": { "summary": "Password validation failed.", "value": { "detail": { "code": "RESET_PASSWORD_INVALID_PASSWORD", "reason": "Password should be at least 3 characters" } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/request-verify-token": { "post": { "tags": [ "auth" ], "summary": "Verify:Request-Token", "operationId": "verify_request_token_api_v1_auth_request_verify_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_verify_request_token_api_v1_auth_request_verify_token_post" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/verify": { "post": { "tags": [ "auth" ], "summary": "Verify:Verify", "operationId": "verify_verify_api_v1_auth_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_verify_verify_api_v1_auth_verify_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" }, "examples": { "VERIFY_USER_BAD_TOKEN": { "summary": "Bad token, not existing user or not the e-mail currently set for the user.", "value": { "detail": "VERIFY_USER_BAD_TOKEN" } }, "VERIFY_USER_ALREADY_VERIFIED": { "summary": "The user is already verified.", "value": { "detail": "VERIFY_USER_ALREADY_VERIFIED" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/api-keys": { "get": { "tags": [ "auth" ], "summary": "Get Api Keys For User", "description": "Get api keys for user \u2014 GET /api/v1/auth/api-keys.", "operationId": "get_api_keys_for_user_api_v1_auth_api_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "auth" ], "summary": "Create Api Key For User", "description": "Create api key for user \u2014 POST /api/v1/auth/api-keys.\n\n## Request Parameters\n- **name** (Optional[str]): Human-readable label to store with the generated API\n key.", "operationId": "create_api_key_for_user_api_v1_auth_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreationPayload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/auth/api-keys/{api_key_id}": { "delete": { "tags": [ "auth" ], "summary": "Delete Api Key For User", "description": "Delete api key for user \u2014 DELETE /api/v1/auth/api-keys/\\{api_key_id\\}.\n\n## Path Parameters\n- **api_key_id** (UUID): UUID of the API key (from GET /api/v1/auth/api-keys).", "operationId": "delete_api_key_for_user_api_v1_auth_api_keys__api_key_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Api Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/add": { "post": { "tags": [ "add" ], "summary": "Add (low level): ingest files, text or URLs into a dataset without building the graph", "description": "Add data to a dataset for processing and knowledge graph construction.\n\nThis endpoint accepts file uploads and string inputs (text, server-side file\npaths, web URLs, GitHub/GitLab repository URLs) and adds them to a specified\ndataset for processing. The data is ingested, analyzed, and integrated into\nthe knowledge graph.\n\n## Request Parameters\n- **data** (List[UploadFile]): Files to upload.\n- **raw_data** (Optional[List[str]]): String inputs, one entry each:\n - Raw text to ingest\n - A local file or directory path on the server (requires ACCEPT_LOCAL_FILE_PATH)\n - A web URL, fetched as a page (requires ALLOW_HTTP_REQUESTS)\n - A GitHub/GitLab repository URL, shallow-cloned and indexed as a code graph\n At least one of data or raw_data is required. Uploads come first, then\n raw_data entries; labels and external_metadata pair with that combined order.\n- **labels** (Optional[str]): JSON array of per-item labels, e.g.\n [\"finance\", \"people\", \"\"], paired positionally with the data items\n (one entry per item; an empty entry skips that item). Stored on each\n item's data record.\n- **external_metadata** (Optional[str]): JSON array of per-item metadata objects,\n e.g. [\\{\"source\": \"crm\"\\}, null], paired positionally with the data items\n (one entry per item; null or \\{\\} skips that item). Merged into each\n item's stored external_metadata.\n- **datasetName** (Optional[str]): Name of the dataset to add data to\n- **datasetId** (Optional[UUID]): UUID of an already existing dataset\n- **node_set** Optional[list[str]]: List of node identifiers for graph organization and access control.\n Used for grouping related data points in the knowledge graph.\n- **run_in_background** (Optional[bool]): Run add pipeline asynchronously (default: False).\n\nEither datasetName or datasetId must be provided.\n\n## Response\nReturns information about the add operation containing:\n- Status of the operation\n- Details about the processed data\n- Any relevant metadata from the ingestion process\n\n## Error Codes\n- **400 Bad Request**: Neither datasetId nor datasetName provided, or neither\n data nor raw_data provided\n- **409 Conflict**: A file in the request already exists in the dataset with\n different content. This endpoint never updates a document; send the new\n version to `PATCH /api/v1/update?data_id=...&dataset_id=...` so the document\n keeps its id. Re-adding identical content is a no-op, not an error.\n- **403 Forbidden**: User doesn't have permission to add to dataset\n\n## Notes\n- To add data to datasets not owned by the user, use dataset_id (when ENABLE_BACKEND_ACCESS_CONTROL is set to True)\n- datasetId value can only be the UUID of an already existing dataset", "operationId": "add_api_v1_add_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_add_api_v1_add_post" }, "example": { "data": "Cognee is a knowledge graph platform for AI applications." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunInfo" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/cognify": { "post": { "tags": [ "cognify" ], "summary": "Cognify (low level): build the knowledge graph from already-added data", "description": "Transform datasets into structured knowledge graphs through cognitive processing.\n\nThis endpoint is the core of Cognee's intelligence layer, responsible for converting\nraw text, documents, and data added through the add endpoint into semantic knowledge graphs.\nIt performs deep analysis to extract entities, relationships, and insights from ingested content.\n\n## Processing Pipeline\n1. Document classification and permission validation\n2. Text chunking and semantic segmentation\n3. Entity extraction using LLM-powered analysis\n4. Relationship detection and graph construction\n5. Vector embeddings generation for semantic search\n6. Content summarization and indexing\n\n## Request Parameters\n- **datasets** (Optional[List[str]]): List of dataset names to process. Dataset names are resolved to datasets owned by the authenticated user.\n- **dataset_ids** (Optional[List[UUID]]): List of existing dataset UUIDs to process. UUIDs allow processing of datasets not owned by the user (if permitted).\n- **run_in_background** (Optional[bool]): Whether to execute processing asynchronously. Defaults to False (blocking).\n- **graph_model** (Optional[dict]): JSON schema describing a custom graph model for entity extraction. When omitted or \\{\\}, the default KnowledgeGraph model is used.\n- **custom_prompt** (Optional[str]): Custom prompt for entity extraction and graph generation. If provided, this prompt will be used instead of the default prompts for knowledge graph extraction.\n- **chunk_size** (Optional[int]): Maximum tokens per chunk. If omitted, Cognee chooses\n a size from the configured LLM and embedding limits.\n- **ontology_key** (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction.\n- **chunks_per_batch** (Optional[int]): Number of chunks to process per task batch in Cognify. Uses the pipeline default when omitted.\n- **data_per_batch** (Optional[int]): Maximum number of data items to process concurrently within a dataset. Defaults to 20.\n\n## Response\n- **Blocking execution**: Complete pipeline run information with entity counts, processing duration, and success/failure status\n- **Background execution**: Pipeline run metadata including pipeline_run_id for status monitoring via WebSocket subscription\n\n## Error Codes\n- **400 Bad Request**: When neither datasets nor dataset_ids are provided\n- **409 Conflict**: When a referenced ontology_key does not exist\n- **500 Internal Server Error**: When the pipeline run errors (e.g. missing LLM API key, database connection failure, or a dataset that does not exist)\n\n## Example Request\n```json\n{\n \"datasets\": [\"research_papers\", \"documentation\"],\n \"run_in_background\": false,\n \"custom_prompt\": \"Extract entities focusing on technical concepts and their relationships. Identify key technologies, methodologies, and their interconnections.\",\n \"ontology_key\": [\"medical_ontology_v1\"]\n}\n```\n\n## Notes\nTo cognify data in datasets not owned by the user and for which the current user has write permission,\nthe dataset_id must be used (when ENABLE_BACKEND_ACCESS_CONTROL is set to True).\n\n## Next Steps\nAfter successful processing, use the search endpoints to query the generated knowledge graph for insights, relationships, and semantic search.", "operationId": "cognify_api_v1_cognify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CognifyPayloadDTO" }, "example": { "datasets": [ "main_dataset" ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/PipelineRunInfo" }, "propertyNames": { "format": "uuid" }, "type": "object", "title": "Response Cognify Api V1 Cognify Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/memify": { "post": { "tags": [ "memify" ], "summary": "Memify", "description": "Enrichment pipeline in Cognee, can work with already built graphs. If no data is provided existing knowledge graph will be used as data,\ncustom data can also be provided instead which can be processed with provided extraction and enrichment tasks.\n\nProvided tasks and data will be arranged to run the Cognee pipeline and execute graph enrichment/creation.\n\n## Request Parameters\n- **extractionTasks** Optional[List[str]]: Names of built-in Cognee Tasks to execute for graph/data extraction.\n Supported names: extract_subgraph, extract_subgraph_chunks, get_triplet_datapoints,\n extract_user_sessions, extract_agent_trace_feedbacks, detect_entity_duplicates.\n Unknown names are rejected with 422. Tasks requiring parameters are SDK-only.\n- **enrichmentTasks** Optional[List[str]]: Names of built-in Cognee Tasks to handle enrichment of provided graph/data from extraction tasks.\n Supported names: cognify_session, cognify_agent_trace_feedback, apply_feedback_weights,\n merge_entity_duplicates, index_data_points.\n- **data** Optional[List[str]]: The data to ingest. Can be any text data when custom extraction and enrichment tasks are used.\n Data provided here will be forwarded to the first extraction task in the pipeline as input.\n If no data is provided the whole graph (or subgraph if node_name/node_type is specified) will be forwarded\n- **dataset_name** (Optional[str]): Name of the datasets to memify\n- **dataset_id** (Optional[UUID]): List of UUIDs of an already existing dataset\n- **node_name** (Optional[List[str]]): Filter graph to specific named entities (for targeted search). Used when no data is provided.\n- **run_in_background** (Optional[bool]): Whether to execute processing asynchronously. Defaults to False (blocking).\n\nEither datasetName or datasetId must be provided.\n\n## Response\nReturns information about the add operation containing:\n- Status of the operation\n- Details about the processed data\n- Any relevant metadata from the ingestion process\n\n## Error Codes\n- **400 Bad Request**: Neither datasetId nor datasetName provided\n- **409 Conflict**: Error during memify operation\n- **403 Forbidden**: User doesn't have permission to use dataset\n- **422 Unprocessable Content**: Unknown task name in extractionTasks/enrichmentTasks\n\n## Notes\n- To memify datasets not owned by the user, use dataset_id (when ENABLE_BACKEND_ACCESS_CONTROL is set to True)\n- datasetId value can only be the UUID of an already existing dataset", "operationId": "memify_api_v1_memify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemifyPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Memify Api V1 Memify Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/search": { "get": { "tags": [ "search" ], "summary": "List the caller's recent search history", "description": "Get search history for the authenticated user.\n\nThis endpoint retrieves the search history for the authenticated user,\nreturning a list of previously executed searches with their timestamps.\n\n## Response\nReturns a list of search history items containing:\n- **id**: Unique identifier for the search\n- **text**: The search query text\n- **user**: User who performed the search\n- **created_at**: When the search was performed\n\n## Error Codes\n- **500 Internal Server Error**: Error retrieving search history", "operationId": "get_search_history_api_v1_search_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SearchHistoryItem" }, "type": "array", "title": "Response Get Search History Api V1 Search Get" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "search" ], "summary": "Search (low level): run one SearchType over the caller's datasets", "description": "Search for nodes in the graph database.\n\nThis endpoint performs semantic search across the knowledge graph to find\nrelevant nodes based on the provided query. It supports different search\ntypes and can be scoped to specific datasets.\n\n## Request Parameters\n- **search_type** (SearchType): Type of search to perform (default: HYBRID_COMPLETION). Use AGENTIC_COMPLETION to enable skills, tools and max_iter.\n- **datasets** (Optional[List[str]]): List of dataset names to search within\n- **dataset_ids** (Optional[List[UUID]]): List of dataset UUIDs to search within\n- **query** (str): The search query string\n- **system_prompt** Optional[str]: System prompt to be used for Completion type searches in Cognee\n- **node_name** Optional[list[str]]: Filter results to specific node_sets defined in the add pipeline (for targeted search).\n- **top_k** (Optional[int]): Maximum number of results to return (default: 15)\n- **only_context** bool: Return what the LLM would have received instead of its answer. For completion type searches the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is `system_prompt_result` with verbose=true. Retrieval-only types return their context. No LLM call is made.\n- **session_id** (Optional[str]): Session whose history and guidance feed the completion or the only_context prompt; the default session when omitted.\n- **verbose** (bool): Return detailed result information including the graph representation when available (default: false)\n- **skills** (Optional[List[str]]): Skill names to load into the agentic retriever (AGENTIC_COMPLETION only)\n- **tools** (Optional[List[str]]): Tool whitelist for AGENTIC_COMPLETION searches\n- **max_iter** (Optional[int]): Max agentic iterations, must be >= 1 (AGENTIC_COMPLETION only)\n- **include_references** (bool): Attach source references to completion-type results (default: true)\n- **code_query** (Optional[dict]): Structured operation arguments for CODE search\n\n## Response\nReturns a list of search results containing relevant nodes from the graph.\n\n## Error Codes\n- **402/403/404/409/422**: Cognee errors (payment required, permission\n denied, missing user, session-dataset conflict, prerequisites not met)\n return their own status code and message via the global error handler\n- **500 Internal Server Error**: Unexpected error during search\n\n## Notes\n- Datasets sent by name will only map to datasets owned by the request sender\n- To search datasets not owned by the request sender, dataset UUID is needed\n- If dataset_ids is provided, the datasets name list is ignored", "operationId": "search_api_v1_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPayloadDTO" }, "example": { "search_type": "GRAPH_COMPLETION", "query": "What is Cognee?", "top_k": 10 } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, { "items": {}, "type": "array" } ], "title": "Response Search Api V1 Search Post" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/permissions/datasets/{principal_id}": { "post": { "tags": [ "permissions" ], "summary": "Give Datasets Permission To Principal", "description": "Grant permission on datasets to a principal (user or role).\n\nThis endpoint allows granting specific permissions on one or more datasets\nto a principal (which can be a user or role). The authenticated user must\nhave appropriate permissions to grant access to the specified datasets.\n\n## Path Parameters\n- **principal_id** (UUID): The UUID of the principal (user or role) to grant permission to\n\n## Request Parameters\n- **permission_name** (str, query): Permission to grant. One of \"read\", \"write\", \"delete\", \"share\".\n- **dataset_ids** (List[UUID], JSON body): Array of dataset UUIDs to grant permission on.\n\n## Response\nReturns a success message indicating permission was assigned.\n\n## Error Codes\n- **400 Bad Request**: Invalid request parameters\n- **403 Forbidden**: User doesn't have permission to grant access\n- **500 Internal Server Error**: Error granting permission", "operationId": "give_datasets_permission_to_principal_api_v1_permissions_datasets__principal_id__post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Principal Id" } }, { "name": "permission_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Permission to grant. One of 'read', 'write', 'delete', 'share'.", "examples": [ "read" ], "title": "Permission Name" }, "description": "Permission to grant. One of 'read', 'write', 'delete', 'share'." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Dataset UUIDs to grant permission on. List your datasets via GET /api/v1/datasets to get real ids.", "examples": [ [ "a1b2c3d4-5717-4562-b3fc-2c963f66afa6" ] ], "title": "Dataset Ids" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "permissions" ], "summary": "Revoke Datasets Permission From Principal", "description": "Revoke permission on datasets from a principal (user or role).\n\n## Path Parameters\n- **principal_id** (UUID): The UUID of the principal to revoke permission from\n\n## Request Parameters\n- **permission_name** (str): The name of the permission to revoke (e.g., \"read\", \"write\", \"delete\")\n- **dataset_ids** (List[UUID]): List of dataset UUIDs to revoke permission on", "operationId": "revoke_datasets_permission_from_principal_api_v1_permissions_datasets__principal_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Principal Id" } }, { "name": "permission_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Permission Name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "title": "Dataset Ids" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/principals/{principal_id}/datasets": { "get": { "tags": [ "permissions" ], "summary": "Get Principal Datasets", "description": "List the datasets a principal holds a permission on.\n\nA principal is a user, a role or a tenant. What the caller may ask about\ndepends on which: themselves or any user if they can manage users; a role\nof this tenant they belong to, or any of its roles if they can manage\nusers; and only the tenant they are currently in. Results are always\nnarrowed to the caller's current tenant.\n\n## Path Parameters\n- **principal_id** (UUID): The principal UUID \u2014 a user, role or tenant.\n\n## Request Parameters\n- **permission_name** (str): Permission to list. Defaults to \"read\".\n\n## Response\nReturns a JSON list of dataset objects the principal has that permission on.\n\n## Error Codes\n- **403 Forbidden**: Caller may not ask about this principal\n- **404 Not Found**: Principal does not exist in the caller's tenant", "operationId": "get_principal_datasets_api_v1_permissions_principals__principal_id__datasets_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Principal Id" } }, { "name": "permission_name", "in": "query", "required": false, "schema": { "type": "string", "description": "Permission to read back. One of 'read', 'write', 'delete', 'share'.", "examples": [ "read" ], "default": "read", "title": "Permission Name" }, "description": "Permission to read back. One of 'read', 'write', 'delete', 'share'." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/roles": { "post": { "tags": [ "permissions" ], "summary": "Create Role", "description": "Create a new role.\n\nThis endpoint creates a new role with the specified name. Roles are used\nto group permissions and can be assigned to users to manage access control\nmore efficiently. The authenticated user becomes the owner of the created role.\n\n## Request Parameters\n- **role_name** (str): The name of the role to create\n\n## Response\nReturns a success message indicating the role was created.\n\n## Error Codes\n- **400 Bad Request**: Invalid role name or role already exists\n- **500 Internal Server Error**: Error creating the role", "operationId": "create_role_api_v1_permissions_roles_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "role_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Name of the role to create. Must be unique within the caller's tenant.", "examples": [ "engineering" ], "title": "Role Name" }, "description": "Name of the role to create. Must be unique within the caller's tenant." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/roles/{role_id}": { "delete": { "tags": [ "permissions" ], "summary": "Delete Role Endpoint", "description": "Delete a role and all its associations.\n\nRemoves all user-role memberships and ACL entries for this role,\nthen deletes the role. The authenticated user must be able to manage\nusers in the tenant.\n\n## Path Parameters\n- **role_id** (UUID): The UUID of the role to delete", "operationId": "delete_role_endpoint_api_v1_permissions_roles__role_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Role Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/users/{user_id}/roles": { "post": { "tags": [ "permissions" ], "summary": "Add User To Role", "description": "Add a user to a role.\n\nThis endpoint assigns a user to a specific role, granting them all the\npermissions associated with that role. The authenticated user must be\nthe owner of the role or have appropriate administrative permissions.\n\n## Path Parameters\n- **user_id** (UUID): The UUID of the user to add to the role\n\n## Request Parameters\n- **role_id** (UUID, query): The UUID of the role to assign the user to\n\n## Response\nReturns a success message indicating the user was added to the role.\n\n## Error Codes\n- **400 Bad Request**: Invalid user or role ID\n- **403 Forbidden**: User doesn't have permission to assign roles\n- **404 Not Found**: User or role doesn't exist\n- **500 Internal Server Error**: Error adding user to role", "operationId": "add_user_to_role_api_v1_permissions_users__user_id__roles_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } }, { "name": "role_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the role to assign. Returned by POST /api/v1/permissions/roles or GET /api/v1/permissions/tenants/\\{tenant_id\\}/roles.", "examples": [ "b2c3d4e5-6717-4562-b3fc-2c963f66afa7" ], "title": "Role Id" }, "description": "UUID of the role to assign. Returned by POST /api/v1/permissions/roles or GET /api/v1/permissions/tenants/\\{tenant_id\\}/roles." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "permissions" ], "summary": "Remove User From Role Endpoint", "description": "Remove a user from a role.\n\nThe authenticated user must be able to manage users in the tenant.\n\n## Path Parameters\n- **user_id** (UUID): The UUID of the user to remove from the role\n\n## Request Parameters\n- **role_id** (UUID): The UUID of the role to remove the user from", "operationId": "remove_user_from_role_endpoint_api_v1_permissions_users__user_id__roles_delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } }, { "name": "role_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Role Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/users/{user_id}/tenants": { "post": { "tags": [ "permissions" ], "summary": "Add User To Tenant", "description": "Add a user to a tenant.\n\nThis endpoint assigns a user to a specific tenant, allowing them to access\nresources and data associated with that tenant. The authenticated user must\nbe the owner of the tenant or have appropriate administrative permissions.\n\n## Path Parameters\n- **user_id** (UUID): The UUID of the user to add to the tenant\n\n## Request Parameters\n- **tenant_id** (UUID): The UUID of the tenant to assign the user to\n\n## Response\nReturns a success message indicating the user was added to the tenant.\n\n## Error Codes\n- **400 Bad Request**: Invalid user or tenant ID\n- **403 Forbidden**: User doesn't have permission to assign tenants\n- **404 Not Found**: User or tenant doesn't exist\n- **500 Internal Server Error**: Error adding user to tenant", "operationId": "add_user_to_tenant_api_v1_permissions_users__user_id__tenants_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } }, { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/{tenant_id}/users/{user_id}": { "delete": { "tags": [ "permissions" ], "summary": "Remove User From Tenant Endpoint", "description": "Remove a user from a tenant.\n\nThe tenant owner or any user with ``has_user_management_permission`` in the\ntenant (e.g. users in the Admin role) can remove users from the tenant. The\ntenant owner cannot be removed from their own tenant. This removes the user\nfrom all roles in the tenant and revokes their permissions on datasets\nbelonging to the tenant. Data owned by the removed user (e.g. datasets they\ncreated) remains in the tenant.\n\n## Path Parameters\n- **tenant_id** (UUID): The UUID of the tenant\n- **user_id** (UUID): The UUID of the user to remove from the tenant\n\n## Response\nReturns a success message indicating the user was removed from the tenant.\n\n## Error Codes\n- **400 Bad Request**: Attempt to remove the tenant owner from their own tenant\n- **403 Forbidden**: Requester is not the tenant owner and does not have\n ``has_user_management_permission`` (e.g. Admin role) in the tenant\n- **404 Not Found**: Tenant not found, user not found, or user not in tenant\n- **500 Internal Server Error**: Error removing user from tenant", "operationId": "remove_user_from_tenant_endpoint_api_v1_permissions_tenants__tenant_id__users__user_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants": { "post": { "tags": [ "permissions" ], "summary": "Create Tenant", "description": "Create a new tenant.\n\nThis endpoint creates a new tenant with the specified name. Tenants are used\nto organize users and resources in multi-tenant environments, providing\nisolation and access control between different groups or organizations.\n\n## Request Parameters\n- **tenant_name** (str): The name of the tenant to create\n\n## Response\nReturns a success message indicating the tenant was created.\n\n## Error Codes\n- **400 Bad Request**: Invalid tenant name or tenant already exists\n- **500 Internal Server Error**: Error creating the tenant", "operationId": "create_tenant_api_v1_permissions_tenants_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_name", "in": "query", "required": true, "schema": { "type": "string", "title": "Tenant Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/select": { "post": { "tags": [ "permissions" ], "summary": "Select Tenant", "description": "Select current tenant.\n\nThis endpoint selects a tenant with the specified UUID. Tenants are used\nto organize users and resources in multi-tenant environments, providing\nisolation and access control between different groups or organizations.\n\nSending a null/None value as tenant_id selects his default single user tenant\n\n## Request Parameters\n- **tenant_id** (Union[UUID, None]): UUID of the tenant to select, If null/None is provided use the default single user tenant\n\n## Response\nReturns a success message along with selected tenant id.", "operationId": "select_tenant_api_v1_permissions_tenants_select_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectTenantDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/permissions/tenants/{tenant_id}/roles": { "get": { "tags": [ "permissions" ], "summary": "Get Tenant Roles", "description": "List roles in a tenant.\n\nCallers who are the tenant owner or have user-management permission (e.g.\nAdmin role) see every role in the tenant. Other callers see only the roles\nthey are a member of.\n\n## Path Parameters\n- **tenant_id** (UUID): The UUID of the tenant (find yours via GET /api/v1/permissions/tenants/me)\n\n## Response\nReturns a JSON list of roles: [\\{\"id\", \"name\", \"description\", \"user_count\"\\}].", "operationId": "get_tenant_roles_api_v1_permissions_tenants__tenant_id__roles_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/{tenant_id}/roles/{role_id}/users": { "get": { "tags": [ "permissions" ], "summary": "Get Users In Role", "description": "List the users assigned to a role.\n\nVisible to members of the role itself, and to callers with user-management\npermission in the tenant.\n\n## Path Parameters\n- **tenant_id** (UUID): The UUID of the tenant\n- **role_id** (UUID): The UUID of the role (list roles via GET /api/v1/permissions/tenants/\\{tenant_id\\}/roles)\n\n## Response\nReturns a JSON list of users: [\\{\"id\", \"name\"\\}] (name is the user's email).\n\n## Error Codes\n- **403 Forbidden**: Caller is not a member of the role and lacks user-management permission\n- **404 Not Found**: The role does not exist in this tenant", "operationId": "get_users_in_role_api_v1_permissions_tenants__tenant_id__roles__role_id__users_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Role Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/{tenant_id}/roles/users/{user_id}": { "get": { "tags": [ "permissions" ], "summary": "Get User Roles", "description": "List the roles assigned to a specific user.\n\nThe authenticated user must have user-management permission in the tenant.\n\n## Path Parameters\n- **tenant_id** (UUID): The UUID of the tenant\n- **user_id** (UUID): The UUID of the user whose roles to list (find user ids via GET /api/v1/permissions/tenants/\\{tenant_id\\}/users)\n\n## Response\nReturns a JSON list of roles scoped to this tenant: [\\{\"id\", \"name\"\\}].\nA member with no roles in the tenant receives an empty list.\n\n## Error Codes\n- **403 Forbidden**: Caller lacks user-management permission in the tenant\n- **404 Not Found**: User does not exist or is not a member of this tenant", "operationId": "get_user_roles_api_v1_permissions_tenants__tenant_id__roles_users__user_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/{tenant_id}/users": { "get": { "tags": [ "permissions" ], "summary": "Get Users In Tenant", "description": "List all users in a tenant, with their roles.\n\nThe authenticated user must be the tenant owner or have user-management\npermission (e.g. Admin role) in the tenant.\n\n## Path Parameters\n- **tenant_id** (UUID): The UUID of the tenant (find yours via GET /api/v1/permissions/tenants/me)\n\n## Response\nReturns a JSON list of users: [\\{\"id\", \"email\", \"roles\": [\\{\"id\", \"name\"\\}]\\}].\n\n## Error Codes\n- **403 Forbidden**: Caller lacks user-management permission in the tenant", "operationId": "get_users_in_tenant_api_v1_permissions_tenants__tenant_id__users_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/permissions/tenants/me": { "get": { "tags": [ "permissions" ], "summary": "Get My Tenants", "description": "List the tenants the authenticated user belongs to.\n\nUse the returned ids as the tenant_id path parameter for the other\n/permissions/tenants/... endpoints.\n\n## Response\nReturns a JSON list of tenants: [\\{\"id\", \"name\"\\}].", "operationId": "get_my_tenants_api_v1_permissions_tenants_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/datasets": { "get": { "tags": [ "datasets" ], "summary": "Get Datasets", "description": "Get all datasets accessible to the authenticated user.\n\nThis endpoint retrieves all datasets that the authenticated user has\nread permissions for. The datasets are returned with their metadata\nincluding ID, name, creation time, and owner information.\n\n## Response\nReturns a list of dataset objects containing:\n- **id**: Unique dataset identifier\n- **name**: Dataset name\n- **created_at**: When the dataset was created\n- **updated_at**: When the dataset was last updated\n- **owner_id**: ID of the dataset owner\n\n## Error Codes\n- **500 Internal Server Error**: Error retrieving datasets", "operationId": "get_datasets_api_v1_datasets_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DatasetDTO" }, "type": "array", "title": "Response Get Datasets Api V1 Datasets Get" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "datasets" ], "summary": "Create New Dataset", "description": "Create a new dataset or return existing dataset with the same name.\n\nThis endpoint creates a new dataset with the specified name. If a dataset\nwith the same name already exists for the user, it returns the existing\ndataset instead of creating a duplicate. The user is automatically granted\nall permissions (read, write, share, delete) on the created dataset.\n\n## Request Parameters\n- **dataset_data** (DatasetCreationPayload): Dataset creation parameters containing:\n - **name**: The name for the new dataset\n\n## Response\nReturns the created or existing dataset object containing:\n- **id**: Unique dataset identifier\n- **name**: Dataset name\n- **created_at**: When the dataset was created\n- **updated_at**: When the dataset was last updated\n- **owner_id**: ID of the dataset owner\n\n## Error Codes\n- **500 Internal Server Error**: Error creating dataset", "operationId": "create_new_dataset_api_v1_datasets_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCreationPayload" }, "example": { "name": "my_dataset", "description": "A test dataset" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "datasets" ], "summary": "Delete All", "description": "Delete all user's data.\n\nThis endpoint permanently deletes all datasets that user created and all its associated data.\nThe user must have delete permissions on the dataset to perform this operation.\n\n## Response\nNo content returned on successful deletion.\nIf no datasets exist for the users, nothing happens.", "operationId": "delete_all_api_v1_datasets_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/datasets/{dataset_id}": { "delete": { "tags": [ "datasets" ], "summary": "Delete Dataset", "description": "Delete a dataset by its ID.\n\nThis endpoint permanently deletes a dataset and all its associated data.\nThe user must have delete permissions on the dataset to perform this operation.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset to delete\n\n## Response\nNo content returned on successful deletion.\n\n## Error Codes\n- **401/403 Unauthorized/Forbidden**: Dataset doesn't exist or user lacks delete permission\n- **500 Internal Server Error**: Error during deletion", "operationId": "delete_dataset_api_v1_datasets__dataset_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" } } }, "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/data/{data_id}": { "delete": { "tags": [ "datasets" ], "summary": "Delete Data", "description": "Delete a specific data item from a dataset.\n\nThis endpoint removes a specific data item from a dataset while keeping\nthe dataset itself intact. The user must have delete permissions on the\ndataset to perform this operation.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset containing the data\n- **data_id** (UUID): The unique identifier of the data item to delete\n\n## Response\nNo content returned on successful deletion.\n\n## Error Codes\n- **401 Unauthorized**: Dataset doesn't exist or user lacks delete permission\n- **500 Internal Server Error**: Error during deletion\n\n## Notes\nDeleting a data_id not tracked in the dataset is treated as a custom-graph-model\ndeletion and returns success.", "operationId": "delete_data_api_v1_datasets__dataset_id__data__data_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" }, { "name": "data_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Data item UUID, from GET /api/v1/datasets/\\{dataset_id\\}/data", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ], "title": "Data Id" }, "description": "Data item UUID, from GET /api/v1/datasets/\\{dataset_id\\}/data" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" } } }, "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/graph": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Graph", "description": "Get the knowledge graph visualization for a dataset.\n\nThis endpoint retrieves the knowledge graph data for a specific dataset,\nincluding nodes and edges that represent the relationships between entities\nin the dataset. The graph data is formatted for visualization purposes.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset\n\n## Response\nReturns the graph data containing:\n- **nodes**: List of graph nodes with id, label, type, and properties\n- **edges**: List of graph edges with source, target, and label\n\n## Error Codes\n- **404 Not Found**: Dataset doesn't exist or user doesn't have access\n- **500 Internal Server Error**: Error retrieving graph data", "operationId": "get_dataset_graph_api_v1_datasets__dataset_id__graph_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/data": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Data", "description": "Get a page of data items in a dataset.\n\nThis endpoint retrieves data items (documents, files, etc.) that belong\nto a specific dataset. Each data item includes metadata such as name, type,\ncreation time, and storage location.\n\nResults are paginated. The response is capped at **limit** items (100 by\ndefault), so this endpoint stays fast on datasets with many documents; page\nthrough with **offset**. Use `GET /{dataset_id}/data/count` for the total.\nThat total is uncapped; offsets above 1,000,000 are rejected, so datasets\nlarger than 1,001,000 items cannot be fully traversed by this endpoint.\nConcurrent inserts/deletes can shift offsets; this is not a snapshot.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset\n\n## Query Parameters\n- **limit** (int, 1-1000, default 100): Maximum number of items to return\n- **offset** (int, default 0): Number of items to skip\n\n## Response\nReturns a list of data objects containing:\n- **id**: Unique data item identifier\n- **name**: Data item name\n- **created_at**: When the data was added\n- **updated_at**: When the data was last updated\n- **extension**: File extension\n- **mime_type**: MIME type of the data\n- **raw_data_location**: Storage location of the raw data\n- **dataset_id**: ID of the containing dataset\n- **label**: Label attached to the data item at upload, if any\n- **external_metadata**: Stored metadata dict (upload-provided keys merged over\n loader-derived ones), if any\n\n## Error Codes\n- **404 Not Found**: Dataset doesn't exist or user doesn't have access\n- **500 Internal Server Error**: Error retrieving data", "operationId": "get_dataset_data_api_v1_datasets__dataset_id__data_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of data items to return.", "default": 100, "title": "Limit" }, "description": "Maximum number of data items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "description": "Number of data items to skip before returning results.", "default": 0, "title": "Offset" }, "description": "Number of data items to skip before returning results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataDTO" }, "title": "Response Get Dataset Data Api V1 Datasets Dataset Id Data Get" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" } } }, "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/data/count": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Data Count", "description": "Count the data items in a dataset.\n\nExists so callers that only need \"how many documents\" do not have to\nfetch the items to count them. `GET /{dataset_id}/data` is paginated,\nso its length is a page size, not a total.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset\n\n## Response\n- **count**: Number of data items in the dataset\n\n## Error Codes\n- **404 Not Found**: Dataset doesn't exist or user doesn't have access\n- **500 Internal Server Error**: Error counting data", "operationId": "get_dataset_data_count_api_v1_datasets__dataset_id__data_count_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCountDTO" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" } } }, "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/status": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Status", "description": "Get the processing status of datasets.\n\nThis endpoint retrieves the current processing status of one or more datasets,\nindicating whether they are being processed, have completed processing, or\nencountered errors during pipeline execution.\n\n## Query Parameters\n- **dataset** (List[UUID]): List of dataset UUIDs to check status for.\n If omitted, returns status for all datasets the user has read permission on\n- **pipeline** (List[str], optional): One or more pipeline names to check.\n - If omitted, defaults to **cognify_pipeline** (backward-compatible behavior)\n - If one pipeline is provided, response is a flat map\n - If multiple pipelines are provided, response is nested per dataset and pipeline\n - **Available options: add_pipeline, cognify_pipeline, code_graph_pipeline**\n - Note: a background code ingest creates its pipeline run only once the\n repository is cloned \u2014 a dataset missing from the response means the run\n has not started yet, not that it failed\n\n## Response\nReturns status information in one of two shapes:\n- Single pipeline (default): \\{dataset_id: status\\}\n- Multiple pipelines: \\{dataset_id: \\{pipeline_name: status\\}\\}\n\nStatus values:\n- **pending**: Dataset is queued for processing\n- **running**: Dataset is currently being processed\n- **completed**: Dataset processing completed successfully\n- **failed**: Dataset processing encountered an error\n\nFor in-flight progress (files completed / total, current stage), see\n**GET /v1/datasets/status/progress** \u2014 a separate endpoint with its own\nfixed response shape, rather than a flag here that would change what\nthis endpoint returns depending on how it's called.\n\n## Error Codes\n- **403 Forbidden**: The request owner cannot read every requested dataset\n- **409 Conflict**: An unexpected error occurred while retrieving status", "operationId": "get_dataset_status_api_v1_datasets_status_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Dataset UUIDs to check (from GET /api/v1/datasets). Omit to get status for all datasets you can read.", "examples": [ [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ] ], "default": [], "title": "Dataset" }, "description": "Dataset UUIDs to check (from GET /api/v1/datasets). Omit to get status for all datasets you can read." }, { "name": "pipeline", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Pipeline names to check: 'add_pipeline', 'cognify_pipeline', or 'code_graph_pipeline' (code ingestion via remember content_type='code'). Omit to default to cognify_pipeline.", "examples": [ [ "cognify_pipeline" ] ], "default": [], "title": "Pipeline" }, "description": "Pipeline names to check: 'add_pipeline', 'cognify_pipeline', or 'code_graph_pipeline' (code ingestion via remember content_type='code'). Omit to default to cognify_pipeline." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PipelineRunStatus" } }, { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PipelineRunStatus" } } } ], "title": "Response Get Dataset Status Api V1 Datasets Status Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/status/progress": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Progress", "description": "Get the processing status of datasets, together with in-flight progress.\n\nSame dataset/pipeline selection as **GET /v1/datasets/status**, but each\nstatus value is always an object \\{status, progress\\} instead of a bare\nstatus \u2014 a dedicated endpoint rather than a flag on /status, so neither\nendpoint's response shape ever depends on how it was called.\n\n## Query Parameters\n- **dataset** (List[UUID]): Dataset UUIDs to check (from GET /api/v1/datasets). Omit to get\n status for all datasets you can read.\n- **pipeline** (List[str]): Pipeline names to check: 'add_pipeline', 'cognify_pipeline', or\n 'code_graph_pipeline' (code ingestion via remember content_type='code'). Omit to default\n to cognify_pipeline.\n\n## Response\n- Single pipeline (default): \\{dataset_id: \\{status, progress\\}\\}\n- Multiple pipelines: \\{dataset_id: \\{pipeline_name: \\{status, progress\\}\\}\\}\n\n**progress** is `null` until the first in-flight progress tick, then an\nobject with `completed_items`, `total_items`, and `current_stage` \u2014\npresent only while the pipeline is running; terminal runs (completed/\nerrored) do not carry a progress snapshot.\n\n## Error Codes\n- **409 Conflict**: Error retrieving status (e.g. requesting a dataset you don't have\n read permission for)", "operationId": "get_dataset_progress_api_v1_datasets_status_progress_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Dataset UUIDs to check (from GET /api/v1/datasets). Omit to get status for all datasets you can read.", "examples": [ [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ] ], "default": [], "title": "Dataset" }, "description": "Dataset UUIDs to check (from GET /api/v1/datasets). Omit to get status for all datasets you can read." }, { "name": "pipeline", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Pipeline names to check: 'add_pipeline', 'cognify_pipeline', or 'code_graph_pipeline' (code ingestion via remember content_type='code'). Omit to default to cognify_pipeline.", "examples": [ [ "cognify_pipeline" ] ], "default": [], "title": "Pipeline" }, "description": "Pipeline names to check: 'add_pipeline', 'cognify_pipeline', or 'code_graph_pipeline' (code ingestion via remember content_type='code'). Omit to default to cognify_pipeline." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PipelineRunStatusWithProgress" } }, { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PipelineRunStatusWithProgress" } } } ], "title": "Response Get Dataset Progress Api V1 Datasets Status Progress Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/graph-summary": { "get": { "tags": [ "datasets" ], "summary": "Get Datasets Graph Summary", "description": "Get node/edge counts per dataset, cached per cognify run.\n\nCounts are computed once per dataset's latest cognify run and cached in\nGraphMetrics, keyed by pipeline_run_id \u2014 orders of magnitude cheaper on\nrepeat polls than GET /\\{dataset_id\\}/graph, which does a full traversal.\n\n## Query Parameters\n- **dataset_ids** (List[UUID], optional): Dataset UUIDs to summarize.\n If omitted, summarizes every dataset the user has read permission on.\n\n## Response\nReturns a list of summaries containing:\n- **datasetId**: The dataset's UUID\n- **pipelineRunId**: The dataset's latest cognify run, or null if it\n has never been cognified\n- **numNodes** / **numEdges**: Graph size for that run\n- **computedAt**: When the count was cached, or null when it wasn't \u2014\n either the last attempt degraded (graph store unavailable, counts\n are 0 and retried on the next poll) or a concurrent caller cached\n the same run first (counts are exact)\n\n## Error Codes\n- **409 Conflict**: The summary could not be built (generic message;\n the detail is server-logged rather than returned). A single\n unreadable graph store does not cause this \u2014 that dataset comes back\n with zero counts \u2014 so this means the relational read itself failed.", "operationId": "get_datasets_graph_summary_api_v1_datasets_graph_summary_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Dataset UUIDs to summarize (from GET /api/v1/datasets). Omit to summarize every dataset you can read.", "examples": [ [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ] ], "default": [], "title": "Dataset Ids" }, "description": "Dataset UUIDs to summarize (from GET /api/v1/datasets). Omit to summarize every dataset you can read." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetGraphSummaryDTO" }, "title": "Response Get Datasets Graph Summary Api V1 Datasets Graph Summary Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/data/{data_id}/raw": { "get": { "tags": [ "datasets" ], "summary": "Get Raw Data", "description": "Download the raw data file for a specific data item.\n\nThis endpoint allows users to download the original, unprocessed data file\nfor a specific data item within a dataset. The file is returned as a direct\ndownload with appropriate headers.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset containing the data\n- **data_id** (UUID): The unique identifier of the data item to download\n\n## Response\nReturns the raw data file as a downloadable response.\n\n## Error Codes\n- **404 Not Found**: Data item doesn't exist in the dataset, or its raw file is missing\n- **500 Internal Server Error**: Error accessing the raw data file\n- **501 Not Implemented**: Raw data is stored on an unsupported storage scheme", "operationId": "get_raw_data_api_v1_datasets__dataset_id__data__data_id__raw_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" }, { "name": "data_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Data item UUID, from GET /api/v1/datasets/\\{dataset_id\\}/data", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ], "title": "Data Id" }, "description": "Data item UUID, from GET /api/v1/datasets/\\{dataset_id\\}/data" } ], "responses": { "200": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/schema": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Schema", "description": "Return the stored graph schema and custom prompt for a dataset.\n\n## Path Parameters\n- **dataset_id** (UUID): UUID of the dataset (from GET /api/v1/datasets).", "operationId": "get_dataset_schema_api_v1_datasets__dataset_id__schema_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Dataset Schema Api V1 Datasets Dataset Id Schema Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "datasets" ], "summary": "Update Dataset Schema", "description": "Store or update the graph schema and custom prompt for a dataset.\n\n## Path Parameters\n- **dataset_id** (UUID): UUID of the dataset (from GET /api/v1/datasets).\n\n## Request Parameters\n- **customPrompt** (Optional[str]): Custom extraction prompt to store for the\n dataset; omitting it leaves any existing prompt unchanged.\n- **graphSchema** (Optional[Dict[str, Any]]): JSON graph schema to store for the\n dataset; omitting it leaves any existing schema unchanged.", "operationId": "update_dataset_schema_api_v1_datasets__dataset_id__schema_put", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetSchemaPayloadDTO" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Dataset Schema Api V1 Datasets Dataset Id Schema Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/datasets/{dataset_id}/processing-status": { "get": { "tags": [ "datasets" ], "summary": "Get Dataset Processing Status", "description": "Get item-level processing status for a dataset.\n\n`GET /status` reports whether a pipeline *run* is in progress or done for a\ndataset. This endpoint answers the finer question operators need when\ntriaging incremental loads: which of the dataset's data items carry the\nper-item completion stamp for a pipeline, and which are still pending.\n\n## Path Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset\n\n## Query Parameters\n- **pipeline** (str, optional): Pipeline name to inspect. Defaults to\n `cognify_pipeline`.\n\n## Response\n- **total**: Number of data items in the dataset\n- **completed**: Items whose per-item status for the pipeline is completed\n (both the legacy string and the dict status representation are recognised)\n- **pending**: `total - completed`\n- **items**: `[{id, name, completed}]`, one entry per data item, in the same\n order as `GET /datasets/{id}/data`. `id` is the data_id accepted by\n `DELETE /datasets/{id}/data/{data_id}` and `forget(data_id=...)`\n\nPer-item errored state is not persisted, so it is not reported: a pending\nitem may be untouched, in progress, or failed.\n\n## Error Codes\n- **404 Not Found**: Dataset doesn't exist or user doesn't have access\n- **409 Conflict**: Error computing the status", "operationId": "get_dataset_processing_status_api_v1_datasets__dataset_id__processing_status_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)", "examples": [ "b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e" ], "title": "Dataset Id" }, "description": "Dataset UUID, the id field from GET /api/v1/datasets (not the name)" }, { "name": "pipeline", "in": "query", "required": false, "schema": { "type": "string", "description": "Pipeline whose per-item completion to count: 'cognify_pipeline' (default), 'add_pipeline', or 'code_graph_pipeline'.", "examples": [ "cognify_pipeline" ], "default": "cognify_pipeline", "title": "Pipeline" }, "description": "Pipeline whose per-item completion to count: 'cognify_pipeline' (default), 'add_pipeline', or 'code_graph_pipeline'." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetProcessingStatusDTO" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" } } }, "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/ontologies": { "get": { "tags": [ "ontologies" ], "summary": "List Ontologies", "description": "List all uploaded ontologies for the authenticated user.\n\n## Response\nReturns a dictionary mapping ontology keys to their metadata including filename, size, and upload timestamp.\n\n## Error Codes\n- **500 Internal Server Error**: File system or processing errors", "operationId": "list_ontologies_api_v1_ontologies_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response List Ontologies Api V1 Ontologies Get" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "ontologies" ], "summary": "Upload Ontology", "description": "Upload a single ontology file for later use in cognify operations.\n\n## Request Parameters\n- **ontology_key** (str): Unique, user-defined identifier for the ontology (plain string \u2014 values starting with '[' or '\\{' are rejected; duplicate keys return 400). Use this key later as the `ontology_key` parameter in /api/v1/cognify or /api/v1/remember.\n- **ontology_file** (UploadFile): Single ontology file in OWL (RDF/XML) format; the filename must end with .owl.\n- **description** (Optional[str]): Optional description for the ontology (plain string; values starting with '[' or '\\{' are rejected).\n\n## Response\nReturns metadata about the uploaded ontology including key, filename, size, and upload timestamp.\n\n## Error Codes\n- **400 Bad Request**: Invalid file format, duplicate key, multiple files uploaded\n- **500 Internal Server Error**: File system or processing errors", "operationId": "upload_ontology_api_v1_ontologies_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_ontology_api_v1_ontologies_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Upload Ontology Api V1 Ontologies Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/ontologies/{ontology_key}": { "delete": { "tags": [ "ontologies" ], "summary": "Delete Ontology", "description": "Delete an uploaded ontology by key.\n\n## Path Parameters\n- **ontology_key** (str): The key of the ontology to delete.\n\n## Error Codes\n- **400 Bad Request**: Ontology key not found\n- **500 Internal Server Error**: File system errors", "operationId": "delete_ontology_api_v1_ontologies__ontology_key__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "ontology_key", "in": "path", "required": true, "schema": { "type": "string", "description": "Key of the ontology to delete, exactly as provided at upload time (see GET /api/v1/ontologies for available keys).", "examples": [ "medical_ontology" ], "title": "Ontology Key" }, "description": "Key of the ontology to delete, exactly as provided at upload time (see GET /api/v1/ontologies for available keys)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Ontology Api V1 Ontologies Ontology Key Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings": { "get": { "tags": [ "settings" ], "summary": "Get Settings", "description": "Get the current system settings.\n\nThis endpoint retrieves the current configuration settings for the system,\nincluding LLM (Large Language Model) configuration and vector database\nconfiguration. These settings determine how the system processes and stores data.\n\n## Response\nReturns the current system settings containing:\n- **llm**: LLM configuration (provider, model, API key)\n- **vector_db**: Vector database configuration (provider, URL, API key)\n\n## Error Codes\n- **500 Internal Server Error**: Error retrieving settings", "operationId": "get_settings_api_v1_settings_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsDTO" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "settings" ], "summary": "Save Settings", "description": "Save or update system settings.\n\nThis endpoint allows updating the system configuration settings. You can\nupdate either the LLM configuration, vector database configuration, or both.\nOnly provided settings will be updated; others remain unchanged.\n\n## Request Parameters\n- **llm** (Optional[LLMConfigInputDTO]): LLM configuration (provider, model, API key)\n- **vector_db** (Optional[VectorDBConfigInputDTO]): Vector database configuration (provider, URL, API key)\n\n## Response\nNo content returned on successful save.\n\n## Error Codes\n- **403 Forbidden**: Caller is not a superuser\n- **400 Bad Request**: Invalid settings provided\n- **500 Internal Server Error**: Error saving settings", "operationId": "save_settings_api_v1_settings_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/visualize": { "get": { "tags": [ "visualize" ], "summary": "Visualize", "description": "Generate an HTML visualization of the dataset's knowledge graph.\n\nBy default renders a bounded subgraph around relevant seed nodes; pass\n``full=true`` to render the entire graph (legacy behavior). Seeds come\nfrom ``query`` or ``seed_node_ids`` when given, otherwise the graph's\nhighest-degree nodes.\n\n## Query Parameters\n- **dataset_id** (UUID): The unique identifier of the dataset to visualize\n- **full** (bool): Render the full graph when true\n- **query** (str): Query string to seed the subgraph via vector search\n- **seed_node_ids** (list[str]): Explicit seed node ids\n- **neighborhood_depth** (int): k-hop expansion depth (default 2)\n- **neighborhood_seed_top_k** (int): Max seeds (default 10)\n- **max_nodes** (int): Node cap after expansion (default 500)\n\n## Response\nReturns an HTML page containing the interactive graph visualization.\n\n## Error Codes\n- **409 Conflict**: Dataset not found, permission denied, or visualization\n failed (detail in the `error` field)\n\n## Notes\n- User must have read permissions on the dataset\n- Visualization is interactive and allows graph exploration", "operationId": "visualize_api_v1_visualize_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "" ], "title": "Dataset Id" }, "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it." }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Render the entire graph instead of a bounded subgraph.", "default": false, "title": "Full" }, "description": "Render the entire graph instead of a bounded subgraph." }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Query string whose nearest vector hits seed the subgraph.", "title": "Query" }, "description": "Query string whose nearest vector hits seed the subgraph." }, { "name": "seed_node_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Explicit seed node ids for subgraph neighborhood expansion.", "title": "Seed Node Ids" }, "description": "Explicit seed node ids for subgraph neighborhood expansion." }, { "name": "neighborhood_depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "k-hop neighborhood depth for subgraph expansion.", "default": 2, "title": "Neighborhood Depth" }, "description": "k-hop neighborhood depth for subgraph expansion." }, { "name": "neighborhood_seed_top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of seed nodes.", "default": 10, "title": "Neighborhood Seed Top K" }, "description": "Maximum number of seed nodes." }, { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "description": "Hard cap on rendered nodes after expansion.", "default": 500, "title": "Max Nodes" }, "description": "Hard cap on rendered nodes after expansion." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/visualize/json": { "get": { "tags": [ "visualize" ], "summary": "Visualize Json", "description": "Return the dataset's knowledge graph as a JSON-safe payload.\n\nSame authorization, dataset resolution and bounded fetch as `GET\n/visualize` \u2014 pass the same arguments to get the JSON behind the\nsame subgraph the HTML page would have shown. Does not include the\nsemantic layout; see `GET /visualize/semantic` for that, computed\nseparately so a client that never opens the semantic tab never pays\nfor it.\n\n## Query Parameters\nSame as `GET /visualize` (dataset_id, full, query, seed_node_ids,\nneighborhood_depth, neighborhood_seed_top_k, max_nodes), plus\n`stream`.\n\n## Response\nA JSON object with `nodes`, `links`, `color_maps`, `schema_graph`,\n`schema_data`, `pipeline_stages`, `edge_classes`, `bundles`,\n`provenance_index`, `has_meaningful_topological_rank`, `memory_map`\nand `search_events`.\n\n## Streaming\nSent when the request has `Accept: text/event-stream` or\n`stream=true`, for graphs too large for one response. Events:\n`meta` (seeds, seed source, bounds); one `chunk` per read, with\ncompact `nodes` (id, name, type, stage, is_unnamed, belongs_to_set,\nsource_node_set) and `links` (source, target, relation, edge_class)\nwhose endpoints were all sent in this or an earlier chunk; `summary`\n(`importance` and `label_priority` per node, split into events of at\nmost one chunk's size, the first also carrying `color_maps.node_set`);\n`done` (totals). A failure after the response started is one\n`error` event with `message` and `status`. The heavy side payloads\nare not streamed, and `full=true` cannot be streamed.\n\n## Error Codes\n- **409 Conflict**: Dataset not found, permission denied, or the\n payload could not be built (generic message; full detail is\n server-logged, not returned, to avoid leaking internals)\n- **Request validation error** (400 on the cognee server, like any\n invalid parameter): `max_nodes` above 5000 without streaming, or\n `full=true` with streaming\n- **503 Service Unavailable**: streamed, and this server already has\n its maximum number of graph streams open; retry shortly\n\n## Notes\n- User must have read permissions on the dataset", "operationId": "visualize_json_api_v1_visualize_json_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "" ], "title": "Dataset Id" }, "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it." }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the entire graph instead of a bounded subgraph.", "default": false, "title": "Full" }, "description": "Include the entire graph instead of a bounded subgraph." }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Query string whose nearest vector hits seed the subgraph.", "title": "Query" }, "description": "Query string whose nearest vector hits seed the subgraph." }, { "name": "seed_node_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Explicit seed node ids for subgraph neighborhood expansion.", "title": "Seed Node Ids" }, "description": "Explicit seed node ids for subgraph neighborhood expansion." }, { "name": "neighborhood_depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "k-hop neighborhood depth for subgraph expansion.", "default": 2, "title": "Neighborhood Depth" }, "description": "k-hop neighborhood depth for subgraph expansion." }, { "name": "neighborhood_seed_top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of seed nodes.", "default": 10, "title": "Neighborhood Seed Top K" }, "description": "Maximum number of seed nodes." }, { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20000, "minimum": 1, "description": "Hard cap on rendered nodes after expansion. Up to 5000 as JSON, up to 20000 when streamed.", "default": 500, "title": "Max Nodes" }, "description": "Hard cap on rendered nodes after expansion. Up to 5000 as JSON, up to 20000 when streamed." }, { "name": "stream", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Stream the graph as server-sent events. Defaults to content negotiation on `Accept`; true or false decides outright.", "title": "Stream" }, "description": "Stream the graph as server-sent events. Defaults to content negotiation on `Accept`; true or false decides outright." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/visualize/semantic": { "get": { "tags": [ "visualize" ], "summary": "Visualize Semantic", "description": "Return semantic positions and clusters for the same subgraph as `GET /visualize/json`.\n\nPass the same arguments used for `GET /visualize/json` to lay out the\nsame subgraph semantically. This is the one call that fetches\nembeddings (up to 2000 nodes) and runs PCA/UMAP over them, so it is\nonly worth calling when the semantic tab is actually open.\n\n## Query Parameters\nSame as `GET /visualize/json`.\n- **dataset_id** (UUID): UUID of the dataset to visualize. List your datasets via GET\n /api/v1/datasets to find it.\n- **full** (bool): Include the entire graph instead of a bounded subgraph. Defaults to\n False.\n- **max_nodes** (int): Hard cap on rendered nodes after expansion. Defaults to 500.\n- **neighborhood_depth** (int): k-hop neighborhood depth for subgraph expansion. Defaults to\n 2.\n- **neighborhood_seed_top_k** (int): Maximum number of seed nodes. Defaults to 10.\n- **query** (Optional[str]): Query string whose nearest vector hits seed the subgraph.\n- **seed_node_ids** (Optional[List[str]]): Explicit seed node ids for subgraph neighborhood\n expansion.\n\n## Response\nA JSON object with `semantic_positions` and `semantic_clusters`,\neither of which is `null` when there are no embeddings to lay out.\n\n## Error Codes\n- **409 Conflict**: Dataset not found, permission denied, or the\n payload could not be built (generic message; full detail is\n server-logged, not returned, to avoid leaking internals)\n\n## Notes\n- User must have read permissions on the dataset", "operationId": "visualize_semantic_api_v1_visualize_semantic_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "" ], "title": "Dataset Id" }, "description": "UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it." }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the entire graph instead of a bounded subgraph.", "default": false, "title": "Full" }, "description": "Include the entire graph instead of a bounded subgraph." }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Query string whose nearest vector hits seed the subgraph.", "title": "Query" }, "description": "Query string whose nearest vector hits seed the subgraph." }, { "name": "seed_node_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Explicit seed node ids for subgraph neighborhood expansion.", "title": "Seed Node Ids" }, "description": "Explicit seed node ids for subgraph neighborhood expansion." }, { "name": "neighborhood_depth", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "k-hop neighborhood depth for subgraph expansion.", "default": 2, "title": "Neighborhood Depth" }, "description": "k-hop neighborhood depth for subgraph expansion." }, { "name": "neighborhood_seed_top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of seed nodes.", "default": 10, "title": "Neighborhood Seed Top K" }, "description": "Maximum number of seed nodes." }, { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "description": "Hard cap on rendered nodes after expansion.", "default": 500, "title": "Max Nodes" }, "description": "Hard cap on rendered nodes after expansion." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/visualize/brains": { "get": { "tags": [ "visualize" ], "summary": "Visualize Brains", "description": "Return every dataset the caller may read, each as a small graph preview.\n\nNo `dataset_id`: this is the Brains overview, not one brain. Built on\nthe same union CLO-399 already uses to decide which datasets a user\ncan see \u2014 their own, their tenant's, and anything granted to a role\nthey belong to \u2014 so a dataset shared with a group appears here with\nno separate authorization logic.\n\n## Query Parameters\n- **max_nodes** (int): Node cap applied independently to each\n dataset (default 500) \u2014 there is no larger, separate cap for \"all\n datasets at once\".\n\n## Response\n`{dataset_id: {\"name\", \"nodes\", \"links\", \"node_set_colors\"}}`.\n\n## Notes\n- Only datasets the caller has read permission on are included", "operationId": "visualize_brains_api_v1_visualize_brains_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "max_nodes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "description": "Hard cap on rendered nodes per dataset.", "default": 500, "title": "Max Nodes" }, "description": "Hard cap on rendered nodes per dataset." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/visualize/brains-summary": { "get": { "tags": [ "visualize" ], "summary": "Visualize Brains Summary", "description": "Return every dataset the caller may read, described from relational metadata.\n\nThe cheap counterpart of `GET /visualize/brains`: the same datasets,\nbut only what an overview shows \u2014 name, sources, size, colors \u2014 built\nfrom relational metadata and the per-cognify-run count cache instead\nof one bounded graph read per dataset. The cost is one count query per\ncognify run whose count is not cached yet, not a graph fetch per\ndataset on every call, so a cold cache pays once per run and every\nlater call pays nothing. `/brains` stays the call to make when the\nnode and link arrays themselves are needed.\n\n## Response\n`{dataset_id: {\"name\", \"source_names\", \"node_count\", \"node_set_colors\"}}`:\n- **name** (str): the dataset's name\n- **source_names** (list[str]): its distinct node set names, sorted;\n empty when the data was ingested without node sets\n- **node_count** (int): nodes in the dataset's graph as of its latest\n cognify run \u2014 the whole graph, not only entity nodes, and 0 for a\n dataset that has never been cognified\n- **node_set_colors** (dict[str, str]): node set colors from the same\n rule `/brains` uses. Same rule and same node sets give the same\n colors, but the two endpoints can be looking at different node\n sets \u2014 `/brains` takes them from a bounded graph fetch (and so sees\n sets that exist only in the graph), this takes them from a full\n relational scan \u2014 and where the sets differ the colors do too\n\n## Error Codes\n- **409 Conflict**: Payload could not be built (generic message; full\n detail is server-logged, not returned, to avoid leaking internals)\n\n## Notes\n- Only datasets the caller has read permission on are included", "operationId": "visualize_brains_summary_api_v1_visualize_brains_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/visualize/live-events": { "get": { "tags": [ "visualize" ], "summary": "Visualize Live Events", "description": "Return search/improve events newer than a cursor, for the Memory tab's live timeline.\n\nMeant to be polled instead of re-fetching the whole `GET\n/visualize/json` payload just to refresh the timeline: pass the\nprevious response's `cursor` back as `since` and only new events\ncome back. The filter is strict, so nothing is ever delivered twice.\n\n## Query Parameters\n- **dataset_id** (UUID): authorization and event scope, see above\n- **since** (datetime, optional): cursor from a previous call\n\n## Response\n`{\"events\": [...], \"cursor\": }`\n\n## Error Codes\n- **403 Forbidden**: Caller lacks read permission on the dataset (or\n it does not exist)\n- **409 Conflict**: Payload could not be built (generic message;\n full detail is server-logged, not returned, to avoid leaking\n internals)\n\n## Notes\n- User must have read permissions on the dataset\n- Events come only from the caller's own sessions attributed to this\n dataset. Sessions carrying no dataset attribution are not included.\n- Attribution is per session, not per answered turn: a session id\n reused across datasets stays with the first dataset it touched, so\n its later turns appear on that dataset's timeline.", "operationId": "visualize_live_events_api_v1_visualize_live_events_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the dataset this poll is for. Gates who may call this endpoint (same read-permission check as every other visualize route) and scopes the events returned: only the caller's own sessions attributed to this dataset contribute.", "examples": [ "" ], "title": "Dataset Id" }, "description": "UUID of the dataset this poll is for. Gates who may call this endpoint (same read-permission check as every other visualize route) and scopes the events returned: only the caller's own sessions attributed to this dataset contribute." }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Cursor from a previous call's response. Omit on the first call to get every available event.", "title": "Since" }, "description": "Cursor from a previous call's response. Omit on the first call to get every available event." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/visualize/multi": { "post": { "tags": [ "visualize" ], "summary": "Visualize Multi", "description": "Generate a combined HTML visualization of graph data from multiple users' datasets.\n\nThis endpoint aggregates knowledge graphs from multiple user+dataset pairs\ninto a single interactive visualization, with each user's nodes tagged for\ncolor-by-user rendering.\n\n## Request Body\nA JSON array of objects, each with:\n- **user_id** (UUID): The user who owns the dataset\n- **dataset_id** (UUID): The dataset to include\n\n## Response\nReturns an HTML page containing the combined interactive graph visualization.\n\n## Error Codes\n- **403 Forbidden**: Caller is not a superuser\n- **409 Conflict**: A user/dataset pair does not exist, is not readable,\n or visualization failed (detail in the `error` field)\n\n## Notes\n- Requires superuser privileges to view other users' data\n- Each user+dataset pair must exist and be accessible", "operationId": "visualize_multi_api_v1_visualize_multi_post", "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/UserDatasetPair" }, "type": "array", "title": "Pairs" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/schema/inventory": { "get": { "tags": [ "schema" ], "summary": "Schema Inventory", "description": "Return the data-derived schema inventory for an authorized dataset.\n\nSummarizes the knowledge graph by semantic type: per-type instance\ncounts, representative sample names, and the per-pair relationship\ndistribution. Wraps the ``get_schema_inventory`` SDK function so it\nis accessible over HTTP with an OpenAPI response schema.\n\nQuery parameters:\n dataset_id: dataset UUID to scope the graph databases.\n samples_per_type: max sample instance names per type (default 5).\n sort: ``\"count\"`` (default) orders types by descending count;\n ``\"none\"`` preserves discovery order.", "operationId": "schema_inventory_api_v1_schema_inventory_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID to scope the graph databases. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "title": "Dataset Id" }, "description": "Dataset UUID to scope the graph databases. List your datasets via GET /api/v1/datasets to find it." }, { "name": "samples_per_type", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 5, "title": "Samples Per Type" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: 'count' (default) orders types by descending instance count; 'none' preserves discovery order. Other values are rejected.", "examples": [ "count" ], "default": "count", "title": "Sort" }, "description": "Sort order: 'count' (default) orders types by descending instance count; 'none' preserves discovery order. Other values are rejected." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaInventoryItem" }, "title": "Response Schema Inventory Api V1 Schema Inventory Get" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__visualize__routers__get_schema_router__ErrorResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__visualize__routers__get_schema_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/schema/provenance": { "get": { "tags": [ "schema" ], "summary": "Schema Provenance", "description": "Return a caller-scoped HTML memory-provenance visualization.\n\nA tenant administrator sees the whole workspace; any other member sees\nonly the datasets they hold a read grant on, and the files, grants,\nagents and sessions hanging off them.\n\nQuery parameters:\n include_memory: when true, also folds the extracted memory\n (entities/relationships) into the provenance view alongside\n data lineage (default false).", "operationId": "schema_provenance_api_v1_schema_provenance_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "include_memory", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include the extracted memory subgraph (entities/relationships) in the provenance visualization.", "default": false, "title": "Include Memory" }, "description": "When true, include the extracted memory subgraph (entities/relationships) in the provenance visualization." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__visualize__routers__get_schema_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/schema/provenance/json": { "get": { "tags": [ "schema" ], "summary": "Schema Provenance Json", "description": "Return a caller-scoped memory-provenance graph as a JSON-safe dict.\n\nSame scoping as `GET /schema/provenance` (the whole tenant for its\nadministrators, the caller's readable datasets for anyone else,\ntenant or not) and the same underlying graph \u2014\npackaged as a dict instead of an HTML page.\n\nQuery parameters:\n include_memory: when true, also folds the extracted memory\n (entities/relationships) into the payload alongside data\n lineage (default false).", "operationId": "schema_provenance_json_api_v1_schema_provenance_json_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "include_memory", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include the extracted memory subgraph (entities/relationships) in the provenance payload.", "default": false, "title": "Include Memory" }, "description": "When true, include the extracted memory subgraph (entities/relationships) in the provenance payload." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__visualize__routers__get_schema_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills": { "post": { "tags": [ "skills" ], "summary": "Ingest Skill", "description": "Ingest a skill from inline SKILL.md markdown (no file upload needed).\n\nJSON-native companion to ``POST /api/v1/remember`` (content_type=skills),\nfor no-code clients. Reuses the same skills ingestion pipeline.\n\n## Request Parameters\n- **dataset_id** (Optional[UUID]): Target dataset UUID (alternative to dataset_name).\n- **dataset_name** (Optional[str]): Target dataset name (created if needed). Required unless\n dataset_id is given.\n- **skill_name** (Optional[str]): Name/slug for the skill (defaults to 'skill').\n- **skills_text** (str): Inline SKILL.md markdown to ingest as a Skill node.", "operationId": "ingest_skill_api_v1_skills_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillIngestRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Ingest Skill Api V1 Skills Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/skills/": { "get": { "tags": [ "skills" ], "summary": "List Dataset Skills", "description": "Return the skills available in an authorized dataset, with publisher metadata.\n\n## Query Parameters\n- **dataset_id** (UUID): Dataset UUID to scope the skills to. List your datasets via GET\n /api/v1/datasets to find it.\n- **include_inactive** (bool): Include skills whose is_active flag is false. Defaults to\n False.\n- **limit** (int): Max skills to return. Defaults to 200.\n- **offset** (int): Number of skills to skip. Defaults to 0.", "operationId": "list_dataset_skills_api_v1_skills__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID to scope the skills to. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "title": "Dataset Id" }, "description": "Dataset UUID to scope the skills to. List your datasets via GET /api/v1/datasets to find it." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include skills whose is_active flag is false.", "default": false, "title": "Include Inactive" }, "description": "Include skills whose is_active flag is false." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Max skills to return.", "default": 200, "title": "Limit" }, "description": "Max skills to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of skills to skip.", "default": 0, "title": "Offset" }, "description": "Number of skills to skip." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillListItem" }, "title": "Response List Dataset Skills Api V1 Skills Get" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/skills/{skill_id}": { "get": { "tags": [ "skills" ], "summary": "Get Dataset Skill", "description": "Return one skill, including its full procedure body.\n\n## Path Parameters\n- **skill_id** (str): ID of the skill (from GET /api/v1/skills/).\n\n## Query Parameters\n- **dataset_id** (UUID): Dataset UUID the skill belongs to.", "operationId": "get_dataset_skill_api_v1_skills__skill_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID the skill belongs to.", "title": "Dataset Id" }, "description": "Dataset UUID the skill belongs to." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDetail" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "skills" ], "summary": "Delete Dataset Skill", "description": "Delete one skill (graph node + embeddings) from an authorized dataset.\n\n## Path Parameters\n- **skill_id** (str): ID of the skill (from GET /api/v1/skills/).\n\n## Query Parameters\n- **dataset_id** (UUID): Dataset UUID the skill belongs to.", "operationId": "delete_dataset_skill_api_v1_skills__skill_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Skill Id" } }, { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID the skill belongs to.", "title": "Dataset Id" }, "description": "Dataset UUID the skill belongs to." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Dataset Skill Api V1 Skills Skill Id Delete" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__skills__routers__get_skills_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/proposals/{proposal_id}": { "get": { "tags": [ "skills" ], "summary": "Get Skill Proposal", "description": "Return one skill-improvement proposal with its before/after procedures.\n\n## Path Parameters\n- **proposal_id** (str): ID of the skill-improvement proposal.\n\n## Query Parameters\n- **dataset_id** (UUID): Dataset UUID the proposal is scoped to. List your datasets via GET\n /api/v1/datasets to find it.", "operationId": "get_skill_proposal_api_v1_proposals__proposal_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Dataset UUID the proposal is scoped to. List your datasets via GET /api/v1/datasets to find it.", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "title": "Dataset Id" }, "description": "Dataset UUID the proposal is scoped to. List your datasets via GET /api/v1/datasets to find it." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetail" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__proposals__routers__get_proposals_router__ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__proposals__routers__get_proposals_router__ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__v1__proposals__routers__get_proposals_router__ErrorResponse" } } }, "description": "Conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/configuration/store_user_configuration": { "post": { "tags": [ "configuration" ], "summary": "Store User Configuration", "description": "Store (upsert) a named configuration for the authenticated user.\n\n## Request Parameters\n- **name** (str): Name of the configuration. If a configuration with the same name\n already exists for this user, it is updated in place.\n- **config** (dict): JSON-serializable configuration data to store (e.g. a KG schema,\n LLM settings, or ingestion parameters).\n\n## Response\nReturns null on success (HTTP 200).", "operationId": "store_user_configuration_api_v1_configuration_store_user_configuration_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePrincipalConfigurationPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/configuration/get_user_configuration/{config_id}": { "get": { "tags": [ "configuration" ], "summary": "Get User Configuration", "description": "Get a stored configuration by its UUID.\n\n## Path Parameters\n- **config_id** (UUID): The \"id\" of a configuration previously returned by\n GET /api/v1/configuration/get_user_configuration/.\n\n## Response\nReturns the stored configuration data as a JSON object. The id may name a\nconfiguration of the authenticated user or of an agent user they are the parent\nof. Returns an empty object \\{\\} with HTTP 200 (not 404) when neither has a\nconfiguration with that id, including when the id belongs to another user's\nconfiguration.", "operationId": "get_user_configuration_api_v1_configuration_get_user_configuration__config_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of a stored configuration (the 'id' field returned by GET /api/v1/configuration/get_user_configuration/).", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "title": "Config Id" }, "description": "UUID of a stored configuration (the 'id' field returned by GET /api/v1/configuration/get_user_configuration/)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get User Configuration Api V1 Configuration Get User Configuration Config Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/configuration/get_user_configuration/": { "get": { "tags": [ "configuration" ], "summary": "Get User All Configuration", "description": "List all configurations stored by the authenticated user and by the agent users\nthey are the parent of.\n\n## Response\nReturns a JSON list of records of the form \\{\"id\", \"ownerId\", \"name\", \"configuration\",\n\"createdAt\", \"updatedAt\"\\}; \"ownerId\" tells the user's own records from an agent's.\nReturns an empty list when none exist. Use the \"id\" value with\nGET /api/v1/configuration/get_user_configuration/\\{config_id\\} to fetch a single\nconfiguration's data.", "operationId": "get_user_all_configuration_api_v1_configuration_get_user_configuration__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": {}, "type": "array", "title": "Response Get User All Configuration Api V1 Configuration Get User Configuration Get" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/delete": { "delete": { "tags": [ "delete" ], "summary": "Delete", "description": "Delete data by its ID from the specified dataset.\n\nArgs:\n data_id: The UUID of the data to delete\n dataset_id: The UUID of the dataset containing the data\n mode: \"soft\" (default) or \"hard\" - hard mode also deletes degree-one entity nodes\n user: Authenticated user\n delete_dataset_if_empty: If True, deletes the dataset if it is left empty after data deletion\n\nReturns:\n JSON response indicating success or failure", "operationId": "delete_api_v1_delete_delete", "deprecated": true, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "data_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Data Id" } }, { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Dataset Id" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "default": "soft", "title": "Mode" } }, { "name": "delete_dataset_if_empty", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Delete Dataset If Empty" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/validate": { "get": { "tags": [ "validate" ], "summary": "Run Validate", "description": "Cross-check the graph and vector stores of a dataset for consistency.\n\nDetects orphaned edges (referencing deleted nodes), nodes whose id no\nlonger matches cognee's own dedup contract, and nodes present in the\ngraph but missing from the vector index (unreachable by semantic\nsearch). Read-only \u2014 never modifies any store.\n\n## Query Parameters\n- **dataset** (List[str]): Dataset name(s) to validate. Omit to validate the default\n dataset.", "operationId": "run_validate_api_v1_validate_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Dataset name(s) to validate. Omit to validate the default dataset.", "default": [ "main_dataset" ], "title": "Dataset" }, "description": "Dataset name(s) to validate. Omit to validate the default dataset." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationReport" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/update": { "patch": { "tags": [ "update" ], "summary": "Update", "description": "Update data in a dataset.\n\nThis endpoint updates existing documents in a specified dataset by providing the data_id of the existing document\nto update and the new document with the changes as the data.\nThe document is updated, analyzed, and the changes are integrated into the knowledge graph.\n\n## Request Parameters\n- **data_id** (UUID, required, query): UUID of the existing document to update (returned by GET /api/v1/datasets/\\{dataset_id\\}/data)\n- **dataset_id** (UUID, required, query): UUID of the dataset containing the document to update\n- **data** (List[UploadFile]): New version of the document that replaces the existing one.\n- **node_set** (Optional[List[str]]): List of node identifiers for graph organization and access control.\n Used for grouping related data points in the knowledge graph.\n- **chunk_level_diff** (bool, query, default true): Replace only the chunks affected\n by the edit instead of re-ingesting the whole document.\n\n## Response\nOne body on every path (`UpdateResult`), a superset of the chunk-level summary\nreturned before:\n- **status**: `\"incremental\"` (chunks replaced), `\"unchanged\"` (no content change),\n `\"full_rebuild\"` (memory dropped and rebuilt from the new content) or `\"failed\"` (the rebuild's\n cognify run errored; `error` says why, and the call can be retried).\n- **regions**, **deleted_chunks**, **added_chunks**, **reused_chunks**,\n **kept_chunks**, **reindexed_chunks**, **total_chunks**: the chunk-level\n counters; `null` on a rebuild, which has no diff.\n- **data_id**, **dataset_id**: the document, the handle to retry with.\n- **duration_seconds**: wall-clock time of the update.\n- **pipeline_run_id**: the run to inspect; `null` for a no-op.\n- **fallback**: set on every rebuild; its `reason` names why the chunk-level path\n did not run (`disabled`, `unsupported_metadata`, `custom_extraction_config`,\n `per_call_db_config`, `unsupported_backend`, `unsupported_chunker`,\n `no_baseline`, `chunks_not_tiling`, `unreadable_text`) and `detail` says it in\n a sentence.\n- **error**: `error_class` and `message` when `status` is `\"failed\"`.\n\n## Error Codes\n- **422 Unprocessable Entity**: data_id or dataset_id missing or not a valid UUID\n- **403 Forbidden**: User lacks write permission on the dataset\n- **404 Not Found**: data_id resolves to no document in the dataset\n- **500 Internal Server Error**: the rebuild's cognify run errored (body is the\n `UpdateResult` with status `\"failed\"`) or an unexpected error occurred\n\n## Notes\n- Chunk-level updates keep unaffected chunks, their entities, and their summaries\n untouched; only the edited region is re-extracted.", "operationId": "update_api_v1_update_patch", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "data_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the existing document to update (returned by GET /api/v1/datasets/\\{dataset_id\\}/data).", "examples": [ "9c4e4a4b-2b1a-4f6e-9d3a-1c2b3d4e5f6a" ], "title": "Data Id" }, "description": "UUID of the existing document to update (returned by GET /api/v1/datasets/\\{dataset_id\\}/data)." }, { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "UUID of the dataset containing the document to update.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "title": "Dataset Id" }, "description": "UUID of the dataset containing the document to update." }, { "name": "chunk_level_diff", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Diff the new content against the stored text and re-ingest only the affected chunks. Falls back to the full rebuild (memory dropped, row refreshed) when chunk-level preconditions are not met.", "default": true, "title": "Chunk Level Diff" }, "description": "Diff the new content against the stored text and re-ingest only the affected chunks. Falls back to the full rebuild (memory dropped, row refreshed) when chunk-level preconditions are not met." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_update_api_v1_update_patch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResult" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } }, "description": "Unprocessable Content" }, "500": { "description": "The rebuild's cognify run errored (an UpdateResult with status \"failed\", naming the error) or an unexpected error occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/UpdateResult" }, { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } ], "title": "Response 500 Update Api V1 Update Patch" } } } } } } }, "/api/v1/responses/": { "post": { "tags": [ "responses" ], "summary": "Create Response", "description": "OpenAI-compatible responses endpoint with function calling support.\n\nThis endpoint provides OpenAI-compatible API responses with integrated\nfunction calling capabilities for Cognee operations.\n\n## Request Parameters\n- **input** (str): The input text to process\n- **model** (str): The model to use for processing\n- **tools** (Optional[List[Dict]]): Available tools for function calling\n- **tool_choice** (Any): Tool selection strategy (default: \"auto\")\n- **temperature** (float): Response randomness (default: 1.0)\n- **maxCompletionTokens** (Optional[int]): Upper bound on tokens generated for the\n completion.\n- **user** (Optional[str]): OpenAI-compatible end-user identifier passed in the\n request body.\n\n## Response\nReturns an OpenAI-compatible response body with function call results.\n\n## Error Codes\n- **400 Bad Request**: Invalid request parameters\n- **500 Internal Server Error**: Error processing request\n\n## Notes\n- Compatible with OpenAI API format\n- Supports function calling with Cognee tools\n- Uses default tools if none provided", "operationId": "create_response_api_v1_responses__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/llm/custom-prompt": { "post": { "tags": [ "llm" ], "summary": "Generate Custom Prompt", "description": "Generate a custom extraction prompt from a provided graph model schema JSON.\n\n## Request Parameters\n- **graphModel** (Dict[str, Any]): Graph model schema as JSON object.\n- **parameters** (Dict[str, Any]): Additional kwargs forwarded to LLMGateway.", "operationId": "generate_custom_prompt_api_v1_llm_custom_prompt_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomPromptGenerationPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomPromptGenerationResponseDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/llm/infer-schema": { "post": { "tags": [ "llm" ], "summary": "Infer Schema", "description": "Analyze sample text and/or uploaded files, and propose a JSON Schema describing the entity types\nand relationships present. The returned schema can be passed directly to\n``/v1/llm/custom-prompt`` or ``/v1/cognify``.\n\n## Request Parameters\n- **data** (List[UploadFile]): Files to load and sample as input for schema\n inference; at least one file or text is required.\n- **parameters** (str): JSON string of additional kwargs forwarded to LLMGateway. Defaults\n to '\\{\\}'.\n- **text** (str): Sample text to analyze for schema inference; at least one file or\n text is required.", "operationId": "infer_schema_api_v1_llm_infer_schema_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_infer_schema_api_v1_llm_infer_schema_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferSchemaResponseDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/sync": { "post": { "tags": [ "sync" ], "summary": "Sync To Cloud", "description": "Sync local data to Cognee Cloud.\n\nThis endpoint triggers synchronization of local Cognee data to your cloud instance.\nIt uploads your local datasets, knowledge graphs, and processed data to the cloud\nfor backup, sharing, or cloud-based processing.\n\n## Request Body (JSON)\n```json\n{\n \"dataset_ids\": [\"123e4567-e89b-12d3-a456-426614174000\", \"456e7890-e12b-34c5-d678-901234567000\"]\n}\n```\n\n## Response\nReturns immediate response for the sync operation:\n- **run_id**: Unique identifier for tracking the background sync operation\n- **status**: Always \"started\" (operation runs in background)\n- **dataset_ids**: List of dataset IDs being synced\n- **dataset_names**: List of dataset names being synced\n- **message**: Description of the background operation\n- **timestamp**: When the sync was initiated\n- **user_id**: User who initiated the sync\n\n## Cloud Sync Features\n- **Automatic Authentication**: Uses your Cognee Cloud credentials\n- **Data Compression**: Optimizes transfer size for faster uploads\n- **Smart Sync**: Automatically handles data updates efficiently\n- **Progress Tracking**: Monitor sync status with sync_id\n- **Error Recovery**: Automatic retry for failed transfers\n- **Data Validation**: Ensures data integrity during transfer\n\n## Example Usage\n```bash\n# Sync multiple datasets to cloud by IDs (JSON request)\ncurl -X POST \"http://localhost:8000/api/v1/sync\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Cookie: auth_token=your-token\" \\\n -d '{\"dataset_ids\": [\"123e4567-e89b-12d3-a456-426614174000\", \"456e7890-e12b-34c5-d678-901234567000\"]}'\n\n# Sync all user datasets (empty request body or null dataset_ids)\ncurl -X POST \"http://localhost:8000/api/v1/sync\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Cookie: auth_token=your-token\" \\\n -d '{}'\n```\n\n## Error Codes\n- **400 Bad Request**: Invalid dataset_ids format\n- **401 Unauthorized**: Invalid or missing authentication\n- **403 Forbidden**: User doesn't have permission to access dataset\n- **404 Not Found**: Dataset not found\n- **409 Conflict**: Sync operation conflict or cloud service unavailable\n- **413 Payload Too Large**: Dataset too large for current cloud plan\n- **429 Too Many Requests**: Rate limit exceeded\n\n## Notes\n- Sync operations run in the background - you get an immediate response\n- Use the returned run_id to track progress (status API coming soon)\n- Large datasets are automatically chunked for efficient transfer\n- Cloud storage usage counts against your plan limits\n- The sync will continue even if you close your connection", "operationId": "sync_to_cloud_api_v1_sync_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/SyncResponse" }, "type": "object", "title": "Response Sync To Cloud Api V1 Sync Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/sync/status": { "get": { "tags": [ "sync" ], "summary": "Get Sync Status Overview", "description": "Check if there are any running sync operations for the current user.\n\nThis endpoint provides a simple check to see if the user has any active sync operations\nwithout needing to know specific run IDs.\n\n## Response\nReturns a simple status overview:\n- **has_running_sync**: Boolean indicating if there are any running syncs\n- **running_sync_count**: Number of currently running sync operations\n- **latest_running_sync** (optional): Information about the most recent running sync if any exists\n\n## Example Usage\n```bash\ncurl -X GET \"http://localhost:8000/api/v1/sync/status\" \\\n -H \"Cookie: auth_token=your-token\"\n```\n\n## Example Responses\n\n**No running syncs:**\n```json\n{\n \"has_running_sync\": false,\n \"running_sync_count\": 0\n}\n```\n\n**With running sync:**\n```json\n{\n \"has_running_sync\": true,\n \"running_sync_count\": 1,\n \"latest_running_sync\": {\n \"run_id\": \"12345678-1234-5678-9012-123456789012\",\n \"dataset_name\": \"My Dataset\",\n \"progress_percentage\": 45,\n \"created_at\": \"2025-01-01T00:00:00Z\"\n }\n}\n```", "operationId": "get_sync_status_overview_api_v1_sync_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/users/me": { "get": { "tags": [ "users" ], "summary": "Users:Current User", "operationId": "users_current_user_api_v1_users_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "401": { "description": "Missing token or inactive user." } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "users" ], "summary": "Users:Patch Current User", "operationId": "users_patch_current_user_api_v1_users_me_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "401": { "description": "Missing token or inactive user." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" }, "examples": { "UPDATE_USER_EMAIL_ALREADY_EXISTS": { "summary": "A user with this email already exists.", "value": { "detail": "UPDATE_USER_EMAIL_ALREADY_EXISTS" } }, "UPDATE_USER_INVALID_PASSWORD": { "summary": "Password validation failed.", "value": { "detail": { "code": "UPDATE_USER_INVALID_PASSWORD", "reason": "Password should beat least 3 characters" } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/users/{id}": { "get": { "tags": [ "users" ], "summary": "Users:User", "operationId": "users_user_api_v1_users__id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "401": { "description": "Missing token or inactive user." }, "403": { "description": "Not a superuser." }, "404": { "description": "The user does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "users" ], "summary": "Users:Patch User", "operationId": "users_patch_user_api_v1_users__id__patch", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "401": { "description": "Missing token or inactive user." }, "403": { "description": "Not a superuser." }, "404": { "description": "The user does not exist." }, "400": { "content": { "application/json": { "examples": { "UPDATE_USER_EMAIL_ALREADY_EXISTS": { "summary": "A user with this email already exists.", "value": { "detail": "UPDATE_USER_EMAIL_ALREADY_EXISTS" } }, "UPDATE_USER_INVALID_PASSWORD": { "summary": "Password validation failed.", "value": { "detail": { "code": "UPDATE_USER_INVALID_PASSWORD", "reason": "Password should beat least 3 characters" } } } }, "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "users" ], "summary": "Users:Delete User", "operationId": "users_delete_user_api_v1_users__id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing token or inactive user." }, "403": { "description": "Not a superuser." }, "404": { "description": "The user does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/users/get-user-id": { "post": { "tags": [ "users" ], "summary": "Get User Id", "description": "Get user id \u2014 POST /api/v1/users/get-user-id.\n\n## Request Parameters\n- **email** (EmailStr): Email address of the user.", "operationId": "get_user_id_api_v1_users_get_user_id_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/checks/connection": { "post": { "tags": [ "checks" ], "summary": "Get Connection Check Endpoint", "description": "Get connection check endpoint \u2014 POST /api/v1/checks/connection.", "operationId": "get_connection_check_endpoint_api_v1_checks_connection_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/health": { "get": { "tags": [ "health" ], "summary": "Health Check", "description": "Health check endpoint for liveness/readiness probes.", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Health Check Health Get" } } } } } } }, "/health/detailed": { "get": { "tags": [ "health" ], "summary": "Detailed Health Check", "description": "Comprehensive health status with component details.", "operationId": "detailed_health_check_health_detailed_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Detailed Health Check Health Detailed Get" } } } } } } }, "/api/v1/agents/list": { "get": { "tags": [ "agent management" ], "summary": "List Agents Endpoint", "description": "List agents endpoint \u2014 GET /api/v1/agents/list.", "operationId": "list_agents_endpoint_api_v1_agents_list_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AgentDTO" }, "type": "array", "title": "Response List Agents Endpoint Api V1 Agents List Get" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/agents/create": { "post": { "tags": [ "agent management" ], "summary": "Create Agent Endpoint", "description": "Create agent endpoint \u2014 POST /api/v1/agents/create.\n\n## Query Parameters\n- **name** (str): Unique name for the new agent user; a conflict is returned if an\n agent with this name exists.", "operationId": "create_agent_endpoint_api_v1_agents_create_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "title": "Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWithApiKeyDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/connections": { "get": { "tags": [ "agent connections" ], "summary": "List Agents Connections", "description": "List agents connections \u2014 GET /api/v1/agents/connections.\n\n## Query Parameters\n- **active_only** (bool): When true, restricts results to connections currently\n considered active. Defaults to True.\n- **agent_id** (Optional[UUID]): Filter connections by agent user ID. Only returns\n connections belonging to this specific agent.\n- **include_sources** (bool): When true, includes the source breakdown for each\n returned connection. Defaults to True.\n- **limit** (int): Maximum number of rows to return. Defaults to 50.\n- **offset** (int): Number of rows to skip for pagination. Defaults to 0.\n- **range** (Literal['24h', '7d', '30d', 'all']): One of: '24h', '7d', '30d', 'all'.\n Defaults to '30d'.\n- **status** (Optional[Literal['active', 'inactive', 'unknown']]): One of: 'active',\n 'inactive', 'unknown'.", "operationId": "list_agents_connections_api_v1_agents_connections_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter connections by agent user ID. Only returns connections belonging to this specific agent.", "title": "Agent Id" }, "description": "Filter connections by agent user ID. Only returns connections belonging to this specific agent." }, { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "default": "30d", "title": "Range" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "active", "inactive", "unknown" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "include_sources", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Sources" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Active Only" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/connections/me": { "get": { "tags": [ "agent connections" ], "summary": "Get My Connection Detail", "description": "Get my connection detail \u2014 GET /api/v1/agents/connections/me.\n\n## Query Parameters\n- **agent_session_name** (Optional[str]): Filter by connection name. Uses the authenticated\n user's ID as the agent ID.", "operationId": "get_my_connection_detail_api_v1_agents_connections_me_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agent_session_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by connection name. Uses the authenticated user's ID as the agent ID.", "title": "Agent Session Name" }, "description": "Filter by connection name. Uses the authenticated user's ID as the agent ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/connections/{agent_id}": { "get": { "tags": [ "agent connections" ], "summary": "Get Connection Detail", "description": "Get connection detail \u2014 GET /api/v1/agents/connections/\\{agent_id\\}.\n\n## Path Parameters\n- **agent_id** (UUID): The agent's user ID (from GET /api/v1/agents/list).\n\n## Query Parameters\n- **agent_session_name** (Optional[str]): Filter by connection name within the agent's\n connections.", "operationId": "get_connection_detail_api_v1_agents_connections__agent_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } }, { "name": "agent_session_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by connection name within the agent's connections.", "title": "Agent Session Name" }, "description": "Filter by connection name within the agent's connections." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/register": { "post": { "tags": [ "agent connections" ], "summary": "Register Agent Endpoint", "description": "Register agent endpoint \u2014 POST /api/v1/agents/register.\n\n## Request Parameters\n- **agent_session_name** (str): A unique name for this agent connection. Combined with the\n authenticated user's ID to identify the connection.\n- **dataset_ids** (List[str]): UUIDs of the datasets (from GET /api/v1/datasets).\n- **dataset_names** (List[str]): Names of the datasets this agent connection reads\n from and writes to.\n- **memory_mode** (Literal['session', 'cognee', 'hybrid', 'none', 'unknown']): One of:\n 'session', 'cognee', 'hybrid', 'none', 'unknown'. Defaults to 'unknown'.\n- **metadata** (Dict[str, Any]): Free-form metadata object.\n- **origin_function** (Optional[str]): Name of the calling function or tool that\n triggered the registration, stored on the connection.\n- **session_id** (Optional[str]): Client-supplied session identifier \u2014 the same value passed\n as session_id to POST /api/v1/remember.\n- **source** (Literal['agent_memory', 'session_trace', 'serve', 'api_key', 'mcp', 'api']):\n One of: 'agent_memory', 'session_trace', 'serve', 'api_key', 'mcp', 'api'. Defaults to\n 'api'.\n- **type** (str): Connection type label recorded for the registered agent. Defaults\n to 'api'.", "operationId": "register_agent_endpoint_api_v1_agents_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/agents/unregister": { "post": { "tags": [ "agent connections" ], "summary": "Unregister Agent Endpoint", "description": "Unregister agent endpoint \u2014 POST /api/v1/agents/unregister.\n\n## Request Parameters\n- **agent_session_name** (str): The name used when registering the connection. Combined with\n the authenticated user's ID to identify which connection to deactivate.", "operationId": "unregister_agent_endpoint_api_v1_agents_unregister_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnregisterAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentModeDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/agents/{agent_id}": { "get": { "tags": [ "agent management" ], "summary": "Get Agent Endpoint", "description": "Get agent endpoint \u2014 GET /api/v1/agents/\\{agent_id\\}.\n\n## Path Parameters\n- **agent_id** (UUID): The agent's user ID (from GET /api/v1/agents/list).", "operationId": "get_agent_endpoint_api_v1_agents__agent_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agent management" ], "summary": "Delete Agent Endpoint", "description": "Delete agent endpoint \u2014 DELETE /api/v1/agents/\\{agent_id\\}.\n\n## Path Parameters\n- **agent_id** (UUID): The agent's user ID (from GET /api/v1/agents/list).", "operationId": "delete_agent_endpoint_api_v1_agents__agent_id__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/activity/pipeline-runs": { "get": { "tags": [ "activity" ], "summary": "Get Pipeline Runs", "description": "Recent `pipeline_runs` rows, newest first, with dataset owner info.\n\nThe table records both pipeline runs and \u2014 since SDK-399 \u2014 one row per\nnon-pipeline operation (`search`, `recall`, `remember`, `forget`,\n`delete`, `prune`). Use the **kind** field to tell them apart:\n\n- `\"pipeline\"` \u2014 a pipeline run (`pipeline_name` is set).\n- `\"operation\"` \u2014 a single-row operation record (`pipeline_name` and\n `status` are NULL, so these are invisible to status-based readers).\n\n## Request Parameters\n- **dataset_id** (Optional[UUID]): Restrict to one dataset (403 if not readable).\n- **pipeline_name** (Optional[str]): Exact-match filter; also excludes\n operation records, which have no `pipeline_name`.\n- **limit** (int): Page size, 1-500 (default: 50).\n- **offset** (int): Rows to skip for pagination (default: 0).\n\nResults are a bare JSON array, not a paged envelope. This endpoint has\nalways returned a top-level array, so wrapping it in a `{\"runs\": [...],\n\"total\": N}` envelope would break every existing caller \u2014 hence no\n`total`. `len(results) == limit` means another page may exist.\n\n## Visibility\nWithout `dataset_id`: rows owned by the caller (and their child agents),\nplus rows on any dataset shared with them. Operation records for\n`recall`, `prune`, and multi-dataset `search` carry no `dataset_id`, so a\ndataset-only filter would omit them entirely.\n\n## Response\nA JSON array. Alongside the original `id`, `pipeline_name`, `status`,\n`dataset_id`, `dataset_name`, `owner_id`, `owner_email`, `created_at`\nand `pipeline_run_id` keys, each row carries the SDK-399 operation\ncolumns. **Every one of them is nullable**: rows written before SDK-399\nwere not backfilled, and each writer sets only the subset it knows.\n\n- **kind** (str): `\"pipeline\"` or `\"operation\"` (never null).\n- **operation_name** (str|null): Operation name; for pipeline rows this\n mirrors `pipeline_name`, so it does *not* distinguish the two kinds.\n- **origin** (str|null): Initiating surface \u2014 `sdk`/`api`/`cli`/`mcp`/`background`.\n- **outcome** (str|null): `\"succeeded\"` / `\"failed\"` / `\"noop\"` (the call ran\n nothing \u2014 e.g. an improve that lost its lock claim). NULL on non-terminal rows.\n **Read together with `background`**: when `background` is true, a\n `\"succeeded\"` outcome means the work was *accepted and started*, not that\n it finished. Treating those rows as completions inflates any success-rate\n or cost figure computed from this feed.\n- **background** (bool|null): True when the call launched background work.\n NULL means not applicable / not recorded.\n- **error_class** (str|null): Exception class name when `outcome=\"failed\"`.\n- **tokens_in** / **tokens_out** (int|null): Provider-billed token counts.\n NULL means *not measured*; `0` means *measured zero* \u2014 do not conflate.\n- **started_at** / **ended_at** (str|null): ISO-8601 timestamps.\n- **user_id** (str|null): Triggering user.\n- **session_id** (str|null): Session-cache id; joins `session_model_usage`.\n- **parent_operation_id** (str|null): Parent's `pipeline_run_id`.\n\n## Aggregation caveats (append-only table)\nRows are append-only, so totals must not be summed naively:\n\n1. A pipeline run emits several rows sharing one `pipeline_run_id`\n (initiated \u2192 started \u2192 terminal). Only the terminal row carries\n `outcome` and `tokens_*`. Deduplicate by `pipeline_run_id` before\n summing, or you will multiply-count.\n2. `parent_operation_id` forms a tree whose token counts already chain\n into the parent. Summing across levels double-counts; sum one level.", "operationId": "get_pipeline_runs_api_v1_activity_pipeline_runs_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict the feed to a single dataset. When given, a missing read permission on that dataset is a 403 rather than an empty list.", "title": "Dataset Id" }, "description": "Restrict the feed to a single dataset. When given, a missing read permission on that dataset is a 403 rather than an empty list." }, { "name": "pipeline_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return only rows whose pipeline_name matches exactly. Operation records carry no pipeline_name, so this excludes them too \u2014 use it to stop a specific pipeline's history being crowded off the page by unrelated operation records.", "title": "Pipeline Name" }, "description": "Return only rows whose pipeline_name matches exactly. Operation records carry no pipeline_name, so this excludes them too \u2014 use it to stop a specific pipeline's history being crowded off the page by unrelated operation records." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page size (max 500).", "default": 50, "title": "Limit" }, "description": "Page size (max 500)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Rows to skip for pagination.", "default": 0, "title": "Offset" }, "description": "Rows to skip for pagination." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/activity/spans": { "get": { "tags": [ "activity" ], "summary": "Get Spans", "description": "Return in-memory OTEL spans from the CogneeSpanExporter buffer.", "operationId": "get_spans_api_v1_activity_spans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/activity/users": { "get": { "tags": [ "activity" ], "summary": "Get Tenant Users", "description": "Return users in the current tenant (includes agents as API key users).", "operationId": "get_tenant_users_api_v1_activity_users_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/activity/agents": { "get": { "tags": [ "activity" ], "summary": "Get Agents", "description": "Return registered agents (users with @cognee.agent emails).", "operationId": "get_agents_api_v1_activity_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/activity/export/{dataset_id}": { "get": { "tags": [ "activity" ], "summary": "Export Dataset Markdown", "description": "Export a dataset's knowledge graph as a Markdown memory report.\n\n## Path Parameters\n- **dataset_id** (UUID): UUID of the dataset (from GET /api/v1/datasets).", "operationId": "export_dataset_markdown_api_v1_activity_export__dataset_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions": { "get": { "tags": [ "sessions" ], "summary": "List Sessions", "description": "Paginated list of sessions.\n\n## Request Parameters\n- **range** (Literal): Time window on last_activity_at: 24h, 7d, 30d, or all\n (default: 30d).\n- **status** (Optional[str]): Effective-status filter: running, completed, failed,\n or abandoned.\n- **limit** (int): Page size, 1-500 (default: 50).\n- **offset** (int): Rows to skip for pagination (default: 0).\n- **order_by** (str): Sort column: last_activity_at, started_at, ended_at, cost_usd,\n tokens_in, or tokens_out (default: last_activity_at).\n- **descending** (bool): Sort newest/largest first (default: true).\n\nResponse envelope:\n\n```\n{\n \"sessions\": [...],\n \"total\": , # rows matching filters before pagination\n \"limit\": ,\n \"offset\": ,\n \"has_more\": ,\n}\n```", "operationId": "list_sessions_api_v1_sessions_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "description": "Time window filtered on last_activity_at: last 24 hours (24h), 7 days (7d), 30 days (30d), or all time (all).", "examples": [ "30d" ], "default": "30d", "title": "Range" }, "description": "Time window filtered on last_activity_at: last 24 hours (24h), 7 days (7d), 30 days (30d), or all time (all)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by effective status: 'running', 'completed', 'failed', or 'abandoned'. 'abandoned' is computed at read time: stored status 'running' with last_activity_at older than SESSION_ABANDON_AFTER_SECONDS (default 30 min). Any other value matches nothing and returns an empty list.", "examples": [ "completed" ], "title": "Status" }, "description": "Filter by effective status: 'running', 'completed', 'failed', or 'abandoned'. 'abandoned' is computed at read time: stored status 'running' with last_activity_at older than SESSION_ABANDON_AFTER_SECONDS (default 30 min). Any other value matches nothing and returns an empty list." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page size (max 500).", "default": 50, "title": "Limit" }, "description": "Page size (max 500)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Rows to skip for pagination.", "default": 0, "title": "Offset" }, "description": "Rows to skip for pagination." }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Column to sort by: last_activity_at, started_at, ended_at, cost_usd, tokens_in, or tokens_out. Unknown values silently fall back to last_activity_at.", "examples": [ "cost_usd" ], "default": "last_activity_at", "title": "Order By" }, "description": "Column to sort by: last_activity_at, started_at, ended_at, cost_usd, tokens_in, or tokens_out. Unknown values silently fall back to last_activity_at." }, { "name": "descending", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Sort descending (newest/largest first).", "default": true, "title": "Descending" }, "description": "Sort descending (newest/largest first)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions/stats": { "get": { "tags": [ "sessions" ], "summary": "Get Stats", "description": "Aggregate counters for the dashboard stat cards + status bar.\n\n## Request Parameters\n- **range** (Literal): Time window on last_activity_at: 24h, 7d, 30d, or all\n (default: 30d).\n\n## Response\nReturns a JSON object with:\n- **sessions** (int): Number of sessions in the window.\n- **total_spend_usd** / **avg_spend_per_session_usd** (float): Cost totals.\n- **tokens_in** / **tokens_out** / **tokens_total** (int): Token totals.\n- **agent_time_s** / **avg_session_s** (float): Summed and average session duration\n in seconds.\n- **success_rate** (float): completed / (completed + failed + abandoned); 1.0 when\n no session has ended yet.\n- **completed** / **failed** / **abandoned** / **running** (int): Effective-status\n counts.", "operationId": "get_stats_api_v1_sessions_stats_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all.", "examples": [ "30d" ], "default": "30d", "title": "Range" }, "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions/cost-by-model": { "get": { "tags": [ "sessions" ], "summary": "Cost By Model", "description": "Cost + token totals grouped by the model that produced them.\n\nAggregates ``session_model_usage`` rows (one per session \u00d7 model),\nso a session that used multiple models splits its cost correctly.\nFilters on ``session_records.last_activity_at`` to scope by\nrange \u2014 requires a join back to the session row.\n\n## Request Parameters\n- **range** (Literal): Time window: 24h, 7d, 30d, or all (default: 30d).", "operationId": "cost_by_model_api_v1_sessions_cost_by_model_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "description": "Time window filtered on session_records.last_activity_at: 24h, 7d, 30d, or all.", "examples": [ "30d" ], "default": "30d", "title": "Range" }, "description": "Time window filtered on session_records.last_activity_at: 24h, 7d, 30d, or all." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions/with-agent-info": { "get": { "tags": [ "sessions" ], "summary": "List Sessions With Agent Info", "description": "Session records merged with their agent-connection metadata (CLO-434).\n\nJoins ``session_records`` to the agent-connections registry on\n``session_id`` so the cloud UI can group/filter usage by client\n(Claude Code, Codex, Slack, MCP, ...) without a second round\ntrip. When no registered connection matches a session, the\nagent type is inferred from the session_id/origin_function\nprefix convention (e.g. ``claude-code-...``, ``codex-...``).\n\nMemory sources are intentionally omitted \u2014 per-agent dataset\nattribution isn't reliably populated yet.\n\nResponse envelope mirrors ``GET /api/v1/sessions``, with each\nsession additionally carrying ``agent_type``, ``agent_source``,\n``agent_session_name``, and ``origin_function``.\n\n## Query Parameters\n- **descending** (bool): Sort in descending order. Defaults to True.\n- **limit** (int): Page size (max 500). Defaults to 50.\n- **offset** (int): Rows to skip for pagination. Defaults to 0.\n- **order_by** (str): Column to sort by. Defaults to 'last_activity_at'.\n- **range** (Literal['24h', '7d', '30d', 'all']): Time window filtered on last_activity_at:\n 24h, 7d, 30d, or all. Defaults to '30d'.\n- **status** (Optional[str]): Effective-status filter: running, completed, failed, or\n abandoned.", "operationId": "list_sessions_with_agent_info_api_v1_sessions_with_agent_info_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all.", "examples": [ "30d" ], "default": "30d", "title": "Range" }, "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Effective-status filter: running, completed, failed, or abandoned.", "title": "Status" }, "description": "Effective-status filter: running, completed, failed, or abandoned." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page size (max 500).", "default": 50, "title": "Limit" }, "description": "Page size (max 500)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Rows to skip for pagination.", "default": 0, "title": "Offset" }, "description": "Rows to skip for pagination." }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "default": "last_activity_at", "title": "Order By" } }, { "name": "descending", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Descending" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions/cost-by-user-agent": { "get": { "tags": [ "sessions" ], "summary": "Cost By User Agent", "description": "Cost + token totals grouped by (user, agent type) \u2014 feeds a\n\"who spends the most, with which agent\" chart (CLO-434 follow-up).\n\nVisibility matches every other endpoint in this router: the\ncaller, their child agents, and dataset-shared sessions. On top\nof that base scope, a tenant owner/admin (same check\n``GET /tenants/{id}/users`` uses) additionally sees every\nmember's spend. A regular member \u2014 or anyone with no tenant,\ni.e. single-user/local mode \u2014 just keeps the base scope rather\nthan being denied outright.\n\n## Query Parameters\n- **range** (Literal['24h', '7d', '30d', 'all']): Time window filtered on last_activity_at:\n 24h, 7d, 30d, or all. Defaults to '30d'.", "operationId": "cost_by_user_agent_api_v1_sessions_cost_by_user_agent_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "type": "string", "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all.", "examples": [ "30d" ], "default": "30d", "title": "Range" }, "description": "Time window filtered on last_activity_at: 24h, 7d, 30d, or all." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/sessions/{session_id}": { "get": { "tags": [ "sessions" ], "summary": "Get Session Detail", "description": "Get session detail \u2014 GET /api/v1/sessions/\\{session_id\\}.\n\n## Path Parameters\n- **session_id** (str): Client-supplied session identifier; the same value passed as\n session_id to POST /api/v1/remember.", "operationId": "get_session_detail_api_v1_sessions__session_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Client-supplied session identifier; the same value passed as session_id to POST /api/v1/remember.", "examples": [ "claude-code-1718000000" ], "title": "Session Id" }, "description": "Client-supplied session identifier; the same value passed as session_id to POST /api/v1/remember." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/remember": { "post": { "tags": [ "remember" ], "summary": "Remember: ingest data and build the knowledge graph (add + cognify + improve)", "description": "Ingest data and build the knowledge graph in a single call.\n\nThis endpoint combines the add and cognify steps. Data is ingested\nfirst, then automatically processed into a structured knowledge graph.\n\n## Request Parameters\n- **data** (List[UploadFile]): Files to upload and process.\n- **raw_data** (Optional[List[str]]): String inputs, one entry each: raw text, a\n local file or directory path on the server (requires ACCEPT_LOCAL_FILE_PATH), a\n web URL fetched as a page (requires ALLOW_HTTP_REQUESTS), or a GitHub/GitLab\n repository URL, shallow-cloned and indexed as a code graph. Uploads come first,\n then raw_data entries; labels and external_metadata pair with that combined\n order. Normal ingestion only \u2014 rejected with content_type. At least one of data\n or raw_data is required for normal ingestion.\n- **labels** (Optional[str]): JSON array of per-file labels, e.g.\n [\"finance\", \"people\", \"\"], paired positionally with the uploaded files (one\n entry per file; an empty entry skips that file). Stored on each file's data\n record. Normal ingestion only \u2014 rejected with session_id or content_type.\n- **external_metadata** (Optional[str]): JSON array of per-file metadata objects,\n e.g. [\\{\"source\": \"crm\"\\}, null], paired positionally with the uploaded files\n (one entry per file; null or \\{\\} skips that file). Merged into each file's\n stored external_metadata. Normal ingestion only \u2014 rejected with session_id\n or content_type.\n- **datasetName** (Optional[str]): Name of the target dataset.\n- **datasetId** (Optional[UUID]): UUID of an existing dataset.\n- **session_id** (Optional[str]): Session to attribute this memory to. When set,\n data is stored in the session cache and bridged into the permanent graph in the\n background; the session is tracked in the sessions dashboard. When omitted,\n data is ingested directly via add + cognify.\n- **node_set** (Optional[List[str]]): Node identifiers for graph organisation.\n- **run_in_background** (Optional[bool]): Run the cognify step asynchronously (default: False).\n- **self_improvement** (Optional[bool]): Run the improve loop after cognify\n (default: True). False gives a plain add + cognify ingestion.\n- **custom_prompt** (Optional[str]): Custom prompt for entity extraction.\n- **chunk_size** (Optional[int]): Maximum tokens per chunk (default: 4096).\n- **chunks_per_batch** (Optional[int]): Chunks per cognify batch.\n- **ontology_key** (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction.\n- **graph_model** (Optional[str]): JSON-serialised graph model schema (same dict format accepted by the cognify endpoint).\n- **content_type** (Optional[str]): Set to \"skills\" to ingest SKILL.md files as\n Skill nodes, or \"code\" to index whole repositories \u2014 each raw_data entry is\n then a git URL or server-local repo path and one code graph is built per\n entry (poll progress via GET /v1/datasets/status?pipeline=code_graph_pipeline);\n each repository is one data item, its id on the result item;\n omit for normal ingestion.\n- **index_vectors** (Optional[bool]): content_type=\"code\" only \u2014 also embed the\n extracted code facts for semantic retrievers (default false, no LLM/embedding\n calls otherwise).\n\nEither datasetName or datasetId must be provided.\n- **import_mode** (Optional[str]): COGX archive imports only: 'preserve' (default),\n 'hybrid', or 're-derive'.\n- **skill_name** (Optional[str]): content_type='skills' + skills_text only: name/slug for\n the inline skill (defaults to 'skill').\n- **skills_text** (Optional[str]): content_type='skills' only: inline SKILL.md markdown to\n ingest without a file upload (no-code path). When set and no files are uploaded, it is\n written to a temporary SKILL.md and ingested via the normal skills pipeline. Pair with\n skill_name to control the resulting skill name.\n\n## Error Codes\n- **400 Bad Request**: Neither datasetId nor datasetName provided, unsupported\n content_type, invalid graph_model JSON/schema, or invalid code-ingestion\n combination (no raw_data repository specs, file uploads or session_id with\n content_type=\"code\", index_vectors without it, or local repo paths while\n ACCEPT_LOCAL_FILE_PATH=false)\n- **409 Conflict**: Error during processing", "operationId": "remember_api_v1_remember_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_remember_api_v1_remember_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Remember Api V1 Remember Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/remember/entry": { "post": { "tags": [ "remember" ], "summary": "Remember a session entry (QA, trace, feedback) into the session cache", "description": "Store a typed memory entry in the session cache.\n\nAccepts a discriminated union of ``QAEntry``, ``TraceEntry``,\n``FeedbackEntry``, or ``SkillRunEntry`` and dispatches to the\nmatching ``remember`` path. Session-backed entries require\n``session_id``; ``SkillRunEntry`` can persist with or without one.\n\n## Request Parameters\n- **dataset_id** (Optional[UUID]): UUID of an existing writable dataset. Takes precedence\n over dataset_name and is required to target a shared dataset by ID.\n- **dataset_name** (str): Name of the target dataset. Defaults to 'main_dataset'.\n- **entry** (Union[QAEntry, TraceEntry, FeedbackEntry, SkillRunEntry]): Typed memory\n entry (qa, trace, feedback, or skill_run) to store, dispatched by its type field.\n- **session_id** (Optional[str]): Required for qa/trace/feedback entries; optional for\n skill_run entries.\n- **skill_improvement** (Optional[dict]): Skill improvement details forwarded to\n remember when recording a skill run.\n\n## Response\nThe returned ``RememberResult`` includes ``entry_type`` and\n``entry_id`` \u2014 the ``qa_id``/``trace_id`` returned by the cache\n(or the ``qa_id`` a feedback was attached to). Use this to chain\nfeedback to a freshly stored QA.", "operationId": "remember_entry_api_v1_remember_entry_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RememberEntryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Remember Entry Api V1 Remember Entry Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/recall": { "get": { "tags": [ "recall" ], "summary": "List the caller's recent recall history", "description": "Get search/recall history for the authenticated user.", "operationId": "get_recall_history_api_v1_recall_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecallHistoryItem" }, "type": "array", "title": "Response Get Recall History Api V1 Recall Get" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "recall" ], "summary": "Recall: query memory with auto-routed search type and session-first lookup", "description": "Recall information from the knowledge graph.\n\nThis is a memory-oriented alias for the search endpoint. All search\ntypes and options from v1 are supported.\n\n## Request Parameters\nField names are shown camelCased in the schema (e.g. searchType, datasetIds,\ntopK); both camelCase and snake_case are accepted.\n\n- **search_type** (Optional[SearchType]): Type of search to perform. Omit\n (default: null) to auto-route the query with the rule-based router\n (HYBRID_COMPLETION fallback); pass a value to pin one.\n- **datasets** (Optional[List[str]]): Dataset names to search within\n- **dataset_ids** (Optional[List[UUID]]): Dataset UUIDs to search within;\n take precedence over dataset names when both are provided\n- **query** (str): The search query string\n- **system_prompt** (Optional[str]): System prompt for completion searches\n- **node_name** (Optional[List[str]]): Filter to specific node sets\n- **top_k** (Optional[int]): Maximum results (default: 15)\n- **only_context** (bool): Return what the LLM would have received instead of\n its answer \u2014 for completion types each item's text is the user prompt\n (conversation history, question plus retrieval context, session guidance)\n and its system_prompt field the retriever's task template; retrieval-only\n types return their context\n- **verbose** (bool): Verbose output\n- **include_references** (bool): Include source/provenance references in\n completion results (default: true)\n- **stream** (Optional[bool]): Stream the answer as server-sent events\n (`text/event-stream`). Defaults to content negotiation on `Accept`.\n- **session_id** (Optional[str]): Session whose cached QA and trace entries\n should be searched\n- **scope** (Optional[str | List[str]]): Memory sources to include: \"graph\",\n \"session\", \"session_first\", \"trace\", \"session_context\", \"tools\", \"code\",\n \"all\", \"auto\", or a list of these (default: \"auto\" \u2014 session first when\n session_id is set, else graph). \"session_first\" requests that short-circuit\n explicitly rather than by omitting searchType. \"code\" is explicit opt-in only\n and returns deterministic code-graph facts tagged source=\"code\"\n (e.g. scope=[\"graph\", \"code\"])\n- **code_query** (Optional[dict]): \"code\" scope only \u2014 operation and arguments\n for the code-graph query (same format as /v1/search code_query); omit for\n the default \"explore\" with the query text as seed\n- **response_schema** (Optional[dict]): JSON Schema for structured\n completion output; validated results land in each result's\n ``structured`` field. 422 on schemas outside the supported subset.\n- **contextProfile** (str): Profile to render for the 'session_context' scope: 'qa'\n (conversational) or 'agent' (tool/workflow). Ignored by other scopes. Defaults to 'qa'.\n- **toolConnections** (Optional[List[str]]): Names of authorized external database\n connections for the 'tools' scope. Omit to use every connection visible to the caller.\n- **toolsTrigger** (str): When the 'tools' scope runs: 'always', or 'on_empty' to query the\n external database only when every other requested source returned nothing. Defaults to\n 'always'.\n\n## Error Codes\n- **402/403/404/409/422**: Cognee errors (payment required, permission\n denied, missing user, session-dataset conflict, prerequisites not met) return their own\n status code and message via the global error handler\n- **409 Conflict**: Unexpected non-Cognee error during recall", "operationId": "recall_api_v1_recall_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseQAEntry" }, { "$ref": "#/components/schemas/ResponseAgentTraceEntry" }, { "$ref": "#/components/schemas/ResponseSessionContextEntry" }, { "$ref": "#/components/schemas/ResponseGraphEntry" }, { "$ref": "#/components/schemas/ResponseCodeEntry" }, { "$ref": "#/components/schemas/ResponseToolEntry" }, { "$ref": "#/components/schemas/ResponseSkillEntry" }, { "$ref": "#/components/schemas/ResponseMarkerEntry" } ], "discriminator": { "propertyName": "source", "mapping": { "session": "#/components/schemas/ResponseQAEntry", "trace": "#/components/schemas/ResponseAgentTraceEntry", "session_context": "#/components/schemas/ResponseSessionContextEntry", "graph": "#/components/schemas/ResponseGraphEntry", "code": "#/components/schemas/ResponseCodeEntry", "tools": "#/components/schemas/ResponseToolEntry", "skills": "#/components/schemas/ResponseSkillEntry", "system": "#/components/schemas/ResponseMarkerEntry" } } }, "type": "array", "title": "Response Recall Api V1 Recall Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/improve": { "post": { "tags": [ "improve" ], "summary": "Improve: enrich and index the graph, optionally bridging sessions into it", "description": "Run the self-improvement loop over a dataset and report what each stage did.\n\nThe nine stages run in a fixed order; each first *gates* (declines work it\ncannot do under the current settings, with no LLM calls) and only then runs:\n`feedback_weights`, `persist_session_qa`, `persist_agent_traces`,\n`extract_agent_context`, `distill_sessions`, `update_user_preferences`,\n`build_truth_subspace`, `triplet_enrichment`, `global_context_index`.\nStages 1-7 need `sessionIds`; stages 7 and 9 are opt-in via the `build*` flags.\n\n## Request Parameters\n- **extraction_tasks** (Optional[List[str]]): Tasks for graph/data extraction.\n- **enrichment_tasks** (Optional[List[str]]): Tasks for graph enrichment.\n- **data** (Optional[str]): Custom input data. Uses existing graph when omitted.\n- **dataset_name** (Optional[str]): Dataset name.\n- **dataset_id** (Optional[UUID]): Dataset UUID.\n- **node_name** (Optional[List[str]]): Filter to specific named entities.\n- **run_in_background** (Optional[bool]): Run all stages as one background\n task and return immediately with `status == \"running\"` (default: False).\n- **build_global_context_index** (Optional[bool]): Build the global context index\n after enrichment (default: False).\n- **build_truth_subspace** (Optional[bool]): Build the truth subspace from the\n sessions' distilled learnings (default: False; needs `sessionIds` and a\n backend with truth state).\n- **feedback_alpha** (Optional[float]): Learning rate in (0, 1] for the\n feedback-weight stage. Omitted means the server's `IMPROVE_FEEDBACK_ALPHA`.\n- **sessionIds** (Optional[List[str]]): Session identifiers whose cached memory\n is bridged into the permanent graph.\n\nEither dataset_name or dataset_id must be provided.\n\n## Response\nAn `ImproveResult`: `status` (`completed`, `errored`, `skipped`, `running`) and\none `stages[]` entry per stage, in order, each with `status`\n(`completed` / `already_completed` / `skipped` / `errored`), a `reason` when\nskipped, `counts`, `duration_ms` and the pipeline `run` when the stage is a\npipeline. A non-fatal stage error is reported inside the body with a 200;\ninspect `status`.\n\n## Error Codes\n- **400 Bad Request**: Neither dataset_id nor dataset_name provided\n- **409 Conflict**: The fatal `persist_session_qa` stage failed \u2014 for a\n Cognee error the body carries the abort reason and the partial\n `improve_result` (what ran before the abort); a non-Cognee error\n returns a deliberately generic body (details go to the logs, never\n the wire). Other Cognee errors return their own status codes.", "operationId": "improve_api_v1_improve_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImprovePayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImproveResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/forget": { "post": { "tags": [ "forget" ], "summary": "Forget data: one item, a dataset, its memory only, or everything", "description": "Remove data from the knowledge graph.\n\n- Set `everything: true` to delete all user data.\n- Set `dataset` or `datasetId` alone to delete an entire dataset.\n- Set `dataset`/`datasetId` + `dataId` to delete a single item.\n- Set `dataset`/`datasetId` + `memoryOnly: true` to clear memory\n (graph + vector), preserving raw files so the dataset can be re-cognified.\n- Set `dataset`/`datasetId` + `dataId` + `memoryOnly: true` to clear memory\n for a single file only.\n\n## Request Parameters\n- **dataId** (Optional[UUID]): UUID of a single data item to remove. Requires\n `dataset` or `datasetId` to also be set.\n- **dataset** (Optional[str]): Name of the dataset to delete or clear.\n- **datasetId** (Optional[UUID]): UUID of the dataset, alternative to `dataset`.\n- **everything** (bool): When true, permanently deletes ALL datasets and data the\n user owns (default: false).\n- **memoryOnly** (bool): When true, delete only memory (graph + vector embeddings),\n preserving raw files and data records (default: false).\n\nProvide either `dataset` or `datasetId`, not both. Field names are shown camelCased\nin the schema; snake_case aliases (`data_id`, `dataset_id`, `memory_only`) are also\naccepted.\n\n## Error Codes\n- **404 Not Found**: Dataset name does not exist or is not accessible\n- **403 Forbidden**: Caller lacks delete permission on the dataset\n- **422 Unprocessable Entity**: Invalid parameter combination (e.g. both `dataset`\n and `datasetId`, `dataId` without a dataset, or `memoryOnly` without a dataset)\n- **500 Internal Server Error**: Error during deletion", "operationId": "forget_endpoint_api_v1_forget_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetPayloadDTO" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Forget Endpoint Api V1 Forget Post" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cognee__api__DTO__ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/slack/history/{team_id}/import": { "post": { "tags": [ "slack" ], "summary": "Import History", "description": "Fetch and index the selection; returns only after native indexing succeeds.\n\nThis is a long-running request. For interactive use, the Slack import\ndialog acknowledges immediately and reports its background result.", "operationId": "import_history_api_v1_slack_history__team_id__import_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Team Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackHistoryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackHistoryResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/slack/history/{team_id}/sync": { "put": { "tags": [ "slack" ], "summary": "Set Sync", "operationId": "set_sync_api_v1_slack_history__team_id__sync_put", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Team Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackSyncSettings" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackSyncSettings" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/slack/history/{team_id}": { "get": { "tags": [ "slack" ], "summary": "History Status", "operationId": "history_status_api_v1_slack_history__team_id__get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Team Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/slack/channels": { "get": { "tags": [ "slack" ], "summary": "Get Channels", "description": "List the connected workspace's public channels, flagging the current allowlist.", "operationId": "get_channels_api_v1_slack_channels_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelListDTO" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "slack" ], "summary": "Set Allowed Channels", "description": "Restrict slash commands to exactly these channel ids.\n\nAn empty list means unrestricted (the default) \u2014 channel scoping is\nopt-in, so a workspace that never visits this settings screen keeps\nworking everywhere, exactly as before this feature existed.\n\n## Request Parameters\n- **channelIds** (List[str]): Slack channel IDs allowed to run slash commands; an\n empty list removes all channel restrictions.", "operationId": "set_allowed_channels_api_v1_slack_channels_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAllowedChannelsPayload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAllowedChannelsResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/slack/link": { "post": { "tags": [ "slack" ], "summary": "Link", "description": "Confirm a ``/cognee-link`` magic-link code for the authenticated caller.\n\nBacks the ``/link-slack`` frontend page \u2014 the browser session here\n(not anything typed into Slack) is what proves which cognee account\nthe invoking Slack member should be linked to.\n\n## Request Parameters\n- **code** (str): Magic-link code issued by /cognee-link, confirmed to bind the\n Slack member to this account.", "operationId": "link_api_v1_slack_link_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmLinkPayload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmLinkResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/status": { "get": { "tags": [ "integrations" ], "summary": "Integrations Status", "description": "Aggregate connection status: every OAuth provider + every known plugin.\n\nOne call powers the whole integrations page. Every registered\nprovider and every known plugin appears, connected or not, with\ndisplay fields only \u2014 never token material. Each status source\n(credentials, identity plugins, legacy prefixes, agent registry) is\nfetched independently and degrades to its empty default on failure:\na broken source logs server-side and blanks its section rather than\n500ing the page (same posture as the sessions list).", "operationId": "integrations_status_api_v1_integrations_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsStatusDTO" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/api/v1/integrations/plugins/{plugin_key}/provision": { "post": { "tags": [ "integrations" ], "summary": "Provision Plugin", "description": "Provision (or re-key) a dedicated agent identity for a plugin.\n\nIdempotent get-or-create: the first call creates an agent sub-user\nfor ``(user, plugin_key)`` with a labeled API key; every later call\nreturns the same agent but rotates the key (old keys are revoked \u2014\nre-provision *is* the rotation flow). The returned key is shown once\nand never retrievable again.\n\n## Path Parameters\n- **plugin_key** (str): Key of a known plugin (see GET /api/v1/integrations/status).", "operationId": "provision_plugin_api_v1_integrations_plugins__plugin_key__provision_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "plugin_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginProvisionDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/plugins/{plugin_key}": { "delete": { "tags": [ "integrations" ], "summary": "Disconnect Plugin", "description": "Disconnect a plugin: revoke its API keys, keep its data.\n\nThe agent user and everything it wrote stay \u2014 deleting data on\ndisconnect would be surprising; full removal stays on\n``DELETE /api/v1/agents/{agent_id}``. Re-provisioning later revives\nthe same identity with a fresh key.\n\n## Path Parameters\n- **plugin_key** (str): Key of a known plugin (see GET /api/v1/integrations/status).", "operationId": "disconnect_plugin_api_v1_integrations_plugins__plugin_key__delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "plugin_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/authorize": { "post": { "tags": [ "integrations" ], "summary": "Authorize", "description": "Mint the provider's authorize URL for the requesting user.\n\nAlso sets the nonce cookie the callback checks. The state alone says\nwhich user *started* an install; the cookie is what says the browser\nfinishing it is the same one. See :func:`_set_install_nonce`.\n\n## Path Parameters\n- **provider** (str): Key of a registered OAuth provider (see GET\n /api/v1/integrations/status).", "operationId": "authorize_api_v1_integrations__provider__authorize_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeUrlDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/connection": { "get": { "tags": [ "integrations" ], "summary": "Connection Status", "description": "Connection state for the Integrations page.\n\n## Path Parameters\n- **provider** (str): Key of a registered OAuth provider (see GET\n /api/v1/integrations/status).", "operationId": "connection_status_api_v1_integrations__provider__connection_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionStatusDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "integrations" ], "summary": "Disconnect", "description": "Disconnect the account connected by the requesting user.\n\nMarks the stored installation revoked, and best-effort asks the\nprovider to kill the token on its own side via\n``integration.revoke_remote``. That call is wrapped here too, on top\nof each adapter's own best-effort handling \u2014 a third-party\nintegration that doesn't honor the \"never raise\" contract on\n``revoke_remote`` still must not block the local disconnect.\n\n## Path Parameters\n- **provider** (str): Key of a registered OAuth provider (see GET\n /api/v1/integrations/status).", "operationId": "disconnect_api_v1_integrations__provider__connection_delete", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } }, { "name": "delete_data", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Delete Data" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/labels": { "get": { "tags": [ "integrations" ], "summary": "Integration Resources", "description": "List selectable resources for a connected integration.\n\n``/folders`` and ``/labels`` are readable aliases for SDK callers that\nwant provider vocabulary; ``/resources`` is the stable generic path.\nThe returned selection is three-state: ``null`` means all resources,\nan empty list means none, and a non-empty list is an allowlist.", "operationId": "integration_resources_api_v1_integrations__provider__labels_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceListDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "integrations" ], "summary": "Set Integration Resources", "description": "Persist a full resource selection for a connected integration.", "operationId": "set_integration_resources_api_v1_integrations__provider__labels_put", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionPayload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/folders": { "get": { "tags": [ "integrations" ], "summary": "Integration Resources", "description": "List selectable resources for a connected integration.\n\n``/folders`` and ``/labels`` are readable aliases for SDK callers that\nwant provider vocabulary; ``/resources`` is the stable generic path.\nThe returned selection is three-state: ``null`` means all resources,\nan empty list means none, and a non-empty list is an allowlist.", "operationId": "integration_resources_api_v1_integrations__provider__folders_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceListDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "integrations" ], "summary": "Set Integration Resources", "description": "Persist a full resource selection for a connected integration.", "operationId": "set_integration_resources_api_v1_integrations__provider__folders_put", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionPayload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/resources": { "get": { "tags": [ "integrations" ], "summary": "Integration Resources", "description": "List selectable resources for a connected integration.\n\n``/folders`` and ``/labels`` are readable aliases for SDK callers that\nwant provider vocabulary; ``/resources`` is the stable generic path.\nThe returned selection is three-state: ``null`` means all resources,\nan empty list means none, and a non-empty list is an allowlist.", "operationId": "integration_resources_api_v1_integrations__provider__resources_get", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceListDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "integrations" ], "summary": "Set Integration Resources", "description": "Persist a full resource selection for a connected integration.", "operationId": "set_integration_resources_api_v1_integrations__provider__resources_put", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionPayload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResourceSelectionResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/integrations/{provider}/sync": { "post": { "tags": [ "integrations" ], "summary": "Sync Integration", "description": "Start a provider sync without changing its stored selection.", "operationId": "sync_integration_api_v1_integrations__provider__sync_post", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSyncResultDTO" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/": { "get": { "summary": "Root", "description": "Root endpoint that returns a welcome message.", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "tags": [ "health" ] } } }, "components": { "schemas": { "AgentDTO": { "properties": { "agentId": { "type": "string", "format": "uuid", "title": "Agentid" }, "agentEmail": { "type": "string", "title": "Agentemail" }, "apiKeyLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apikeylabel" } }, "type": "object", "required": [ "agentId", "agentEmail" ], "title": "AgentDTO" }, "AgentModeDTO": { "properties": { "activeAgents": { "type": "integer", "title": "Activeagents" } }, "type": "object", "required": [ "activeAgents" ], "title": "AgentModeDTO" }, "AgentWithApiKeyDTO": { "properties": { "agentId": { "type": "string", "format": "uuid", "title": "Agentid" }, "agentEmail": { "type": "string", "title": "Agentemail" }, "agentApiKey": { "type": "string", "title": "Agentapikey" } }, "type": "object", "required": [ "agentId", "agentEmail", "agentApiKey" ], "title": "AgentWithApiKeyDTO" }, "ApiKeyCreationPayload": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "ApiKeyCreationPayload" }, "AuthorizeUrlDTO": { "properties": { "authorizeUrl": { "type": "string", "title": "Authorizeurl" } }, "type": "object", "required": [ "authorizeUrl" ], "title": "AuthorizeUrlDTO" }, "Body_add_api_v1_add_post": { "properties": { "data": { "items": { "type": "string", "format": "binary" }, "type": "array", "title": "Data" }, "raw_data": { "anyOf": [ { "items": { "type": "string", "example": "" }, "type": "array" }, { "type": "null" } ], "title": "Raw Data", "description": "Data given as strings instead of uploads, one entry each: raw text to ingest, a local file or directory path on the server's filesystem (requires ACCEPT_LOCAL_FILE_PATH), a web URL to fetch (requires ALLOW_HTTP_REQUESTS), or a GitHub/GitLab repository URL, which is shallow-cloned and indexed as a code graph by cognify. Combined with 'data': uploads come first, then these entries; labels and external_metadata pair with that combined order. Empty entries are ignored.", "examples": [ [] ] }, "labels": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Labels", "description": "Per-item labels, e.g. [\"finance\", \"people\", \"\"] \u2014 the Nth label applies to the Nth data item (uploads first, then raw_data entries), one entry per item, an empty entry skips that item. The comma-separated form \"finance,people,\" is accepted equivalently (it is what Swagger UI sends when you type a JSON array here), so labels cannot contain commas unless the client sends real JSON. Stored on each item's data record and returned when listing dataset data.", "examples": [ "" ] }, "external_metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Metadata", "description": "JSON array of per-file metadata objects, e.g. [\\{\"source\": \"crm\", \"ticket\": 42\\}, null]. Paired positionally like labels: the Nth entry applies to the Nth uploaded file (null or \\{\\} skips that file), and one entry per file is required when any is given. Merged into the file's stored external_metadata (your keys win over loader-derived ones; 'node_set' is reserved) and returned when listing dataset data.", "examples": [ "" ] }, "datasetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Datasetname", "description": "Name of the target dataset (created if it does not exist). Required unless datasetId is provided.", "examples": [ "default_dataset" ] }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "const": "" }, { "type": "null" } ], "title": "Datasetid", "description": "Providing dataset ID is mandatory for sharing a dataset between users. Datasets provided by name will only be resolvable by dataset owner.", "examples": [ "" ] }, "node_set": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Node Set", "default": [ "" ] }, "run_in_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Run In Background", "default": false } }, "type": "object", "title": "Body_add_api_v1_add_post" }, "Body_infer_schema_api_v1_llm_infer_schema_post": { "properties": { "data": { "items": { "type": "string", "format": "binary" }, "type": "array", "title": "Data" }, "text": { "type": "string", "title": "Text" }, "parameters": { "type": "string", "title": "Parameters", "description": "JSON string of additional kwargs forwarded to LLMGateway.", "default": "{}" } }, "type": "object", "title": "Body_infer_schema_api_v1_llm_infer_schema_post" }, "Body_login_api_v1_auth_login_post": { "properties": { "grant_type": { "anyOf": [ { "type": "string", "pattern": "^password$" }, { "type": "null" } ], "title": "Grant Type" }, "username": { "type": "string", "title": "Username" }, "password": { "type": "string", "format": "password", "title": "Password" }, "scope": { "type": "string", "title": "Scope", "default": "" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "password", "title": "Client Secret" } }, "type": "object", "required": [ "username", "password" ], "title": "Body_login_api_v1_auth_login_post" }, "Body_remember_api_v1_remember_post": { "properties": { "data": { "items": { "type": "string", "format": "binary" }, "type": "array", "title": "Data" }, "raw_data": { "anyOf": [ { "items": { "type": "string", "example": "" }, "type": "array" }, { "type": "null" } ], "title": "Raw Data", "description": "Data given as strings instead of uploads, one entry each: raw text to remember, a local file or directory path on the server's filesystem (requires ACCEPT_LOCAL_FILE_PATH), a web URL to fetch (requires ALLOW_HTTP_REQUESTS), or a GitHub/GitLab repository URL, which is shallow-cloned and indexed as a code graph. Combined with 'data': uploads come first, then these entries; labels and external_metadata pair with that combined order. Empty entries are ignored. With content_type='code' every entry is a repository spec (git URL or server-local repo path) and one code graph is built per entry; rejected with content_type='skills' or 'cogx-archive', which take file uploads.", "examples": [ [] ] }, "labels": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Labels", "description": "Per-file labels, e.g. [\"finance\", \"people\", \"\"] \u2014 the Nth label applies to the Nth uploaded file, one entry per file, an empty entry skips that file. The comma-separated form \"finance,people,\" is accepted equivalently (it is what Swagger UI sends when you type a JSON array here), so labels cannot contain commas unless the client sends real JSON. Stored on each file's data record and returned when listing dataset data. Only supported for normal ingestion \u2014 rejected when combined with session_id or content_type.", "examples": [ "" ] }, "external_metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Metadata", "description": "JSON array of per-file metadata objects, e.g. [\\{\"source\": \"crm\", \"ticket\": 42\\}, null]. Paired positionally like labels: the Nth entry applies to the Nth uploaded file (null or \\{\\} skips that file), and one entry per file is required when any is given. Merged into the file's stored external_metadata (your keys win over loader-derived ones; 'node_set' is reserved). Only supported for normal ingestion \u2014 rejected when combined with session_id or content_type.", "examples": [ "" ] }, "datasetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Datasetname", "description": "Name of the target dataset (created if it does not exist). Required unless datasetId is provided.", "examples": [ "default_dataset" ] }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "const": "" }, { "type": "null" } ], "title": "Datasetid", "examples": [ "" ] }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id", "description": "Session to attribute this memory to (e.g. claude-code-1718000000). When set, the data is stored in the session cache (and bridged into the permanent graph in the background) and the session appears in the sessions dashboard. Leave empty for a direct add+cognify.", "examples": [ "" ] }, "node_set": { "anyOf": [ { "items": { "type": "string", "example": "" }, "type": "array" }, { "type": "null" } ], "title": "Node Set", "description": "Tags the ingested data with named node sets (e.g. per-agent or per-project groups). Extracted graph nodes are linked to these sets, and recall/search can later be restricted to them via their node_name parameter. Leave empty to skip tagging.", "examples": [ [] ] }, "self_improvement": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Self Improvement", "description": "False skips automatic improvement after ingestion, or the background graph bridge for session text. Ingestion/session storage still runs. Omit to preserve the core default (currently true)." }, "run_in_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Run In Background", "description": "If true, the request returns immediately (status 'running' with a pipeline_run_id) while ingestion and graph building continue server-side \u2014 poll GET /v1/datasets/status to track completion. If false, the request blocks until the knowledge graph is fully built, which can take minutes for large files.", "default": false }, "custom_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Prompt", "description": "Replaces the default entity-extraction prompt used during graph building. Use it to steer which entities and relationships get extracted (e.g. focus on technical concepts, people, or contracts). Leave empty for the default prompt.", "default": "" }, "chunk_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Chunk Size", "description": "Maximum tokens per text chunk during ingestion (default: 4096). Each chunk is processed by the LLM separately for entity extraction: larger chunks give more context per extraction but fewer, coarser passes; smaller chunks give finer-grained extraction at higher LLM cost.", "default": 4096 }, "chunks_per_batch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Chunks Per Batch", "description": "Number of chunks processed per cognify task batch (default: 36). Controls ingestion parallelism/throughput; rarely needs changing.", "default": 36 }, "ontology_key": { "anyOf": [ { "items": { "type": "string", "example": "" }, "type": "array" }, { "type": "null" } ], "title": "Ontology Key", "description": "Keys of previously uploaded ontologies (see /v1/ontologies) to ground entity extraction. Leave empty to ingest without an ontology.", "examples": [ [] ] }, "graph_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Graph Model", "description": "JSON-serialised graph model schema (same format as the cognify endpoint), e.g. \\{\"title\": \"CompanyGraph\", \"type\": \"object\", \"properties\": \\{...\\}\\}. Must include a top-level 'title' key. Leave empty to use the default KnowledgeGraph model \u2014 a restrictive schema here can produce an empty graph. Invalid JSON or an unconvertible schema is rejected with 400.", "examples": [ "" ] }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type", "description": "Set to 'skills' to ingest SKILL.md files as dataset-scoped Skill nodes, or 'code' to index whole code repositories (pass git URLs or server-local repo paths via 'raw_data') as an architectural code graph through the enola-backed pipeline. Leave empty for normal ingestion.", "examples": [ "" ] }, "import_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Import Mode", "description": "COGX archive imports only: 'preserve' (default), 'hybrid', or 're-derive'.", "examples": [ "" ] }, "skills_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skills Text", "description": "content_type='skills' only: inline SKILL.md markdown to ingest without a file upload (no-code path). When set and no files are uploaded, it is written to a temporary SKILL.md and ingested via the normal skills pipeline. Pair with skill_name to control the resulting skill name.", "examples": [ "" ] }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name", "description": "content_type='skills' + skills_text only: name/slug for the inline skill (defaults to 'skill').", "examples": [ "" ] }, "index_vectors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Index Vectors", "description": "content_type='code' only: also embed the extracted code facts so semantic/completion retrievers can see them (requires an embedding provider). Default false \u2014 the code graph pipeline is deterministic and makes no LLM or embedding calls, and SearchType.CODE uses graph indexes only.", "default": false } }, "type": "object", "title": "Body_remember_api_v1_remember_post" }, "Body_reset_forgot_password_api_v1_auth_forgot_password_post": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "Body_reset_forgot_password_api_v1_auth_forgot_password_post" }, "Body_reset_reset_password_api_v1_auth_reset_password_post": { "properties": { "token": { "type": "string", "title": "Token" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "token", "password" ], "title": "Body_reset_reset_password_api_v1_auth_reset_password_post" }, "Body_update_api_v1_update_patch": { "properties": { "data": { "items": { "type": "string", "format": "binary" }, "type": "array", "title": "Data", "description": "New version of the document that replaces the existing one. With chunk_level_diff enabled (default) only the chunks affected by the edit are replaced; otherwise the document is deleted and re-ingested." }, "node_set": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Node Set", "description": "Node identifiers for graph organization and access control.", "default": [ "" ], "examples": [ [ "user_memories" ] ] } }, "type": "object", "required": [ "data" ], "title": "Body_update_api_v1_update_patch" }, "Body_upload_ontology_api_v1_ontologies_post": { "properties": { "ontology_key": { "type": "string", "title": "Ontology Key", "description": "Unique, user-defined identifier for this ontology. Reference it later via the ontology_key parameter of the cognify/remember endpoints.", "examples": [ "medical_ontology" ] }, "ontology_file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Ontology File", "description": "Single ontology file in OWL (RDF/XML) format. The filename must end with .owl \u2014 other extensions are rejected with 400. Exactly one file per request." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Optional human-readable description (plain string; values starting with '[' or '\\{' are rejected).", "examples": [ "OWL ontology of medical conditions and treatments" ] } }, "type": "object", "required": [ "ontology_key", "ontology_file" ], "title": "Body_upload_ontology_api_v1_ontologies_post" }, "Body_verify_request_token_api_v1_auth_request_verify_token_post": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "Body_verify_request_token_api_v1_auth_request_verify_token_post" }, "Body_verify_verify_api_v1_auth_verify_post": { "properties": { "token": { "type": "string", "title": "Token" } }, "type": "object", "required": [ "token" ], "title": "Body_verify_verify_api_v1_auth_verify_post" }, "ChannelDTO": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "isPrivate": { "type": "boolean", "title": "Isprivate" }, "allowed": { "type": "boolean", "title": "Allowed" } }, "type": "object", "required": [ "id", "name", "isPrivate", "allowed" ], "title": "ChannelDTO" }, "ChannelListDTO": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/ChannelDTO" }, "type": "array", "title": "Channels" } }, "type": "object", "required": [ "channels" ], "title": "ChannelListDTO" }, "ChatUsage": { "properties": { "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "default": 0 }, "completion_tokens": { "type": "integer", "title": "Completion Tokens", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "default": 0 } }, "type": "object", "title": "ChatUsage", "description": "Token usage information" }, "CogneeModel": { "type": "string", "enum": [ "cognee-v1" ], "title": "CogneeModel", "description": "Enum for supported model types" }, "CognifyPayloadDTO": { "properties": { "datasets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Datasets", "description": "Dataset names to process; resolved against datasets owned by the authenticated user.", "examples": [ [ "default_dataset" ] ] }, "datasetIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Datasetids", "description": "Dataset UUIDs to process (required for datasets shared with you). Takes precedence over the datasets name list when both are provided.", "examples": [ [] ] }, "runInBackground": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Runinbackground", "description": "If true, the request returns immediately with a pipeline_run_id while the graph builds server-side \u2014 track completion via GET /v1/datasets/status or the /v1/cognify/subscribe WebSocket. If false, the request blocks until the knowledge graph is fully built, which can take minutes for large datasets.", "default": false }, "graphModel": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Graphmodel", "description": "JSON schema describing a custom graph model for entity extraction, including a top-level 'title' key. When omitted or \\{\\}, the default KnowledgeGraph model is used \u2014 a restrictive schema here can produce an empty graph.", "examples": [ {} ] }, "customPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customprompt", "description": "Replaces the default entity-extraction prompt to steer which entities and relationships get extracted (e.g. 'Extract entities focusing on technical concepts and their relationships.'). Leave empty for the default prompt.", "default": "", "examples": [ "" ] }, "chunkSize": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Chunksize", "description": "Maximum tokens per chunk (e.g. 4096). Leave null for automatic model-based sizing. Larger chunks give more context per LLM extraction pass; smaller chunks give finer-grained extraction at higher LLM cost.", "examples": [ null ] }, "ontologyKey": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ontologykey", "description": "Keys of previously uploaded ontologies (see /v1/ontologies) to ground entity extraction. Leave empty to process without an ontology.", "examples": [ [] ] }, "chunksPerBatch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Chunksperbatch", "description": "Number of chunks to process per task batch (e.g. 36). Controls processing parallelism/throughput; leave null for the pipeline default. Higher the value higher the parallelism/throughput", "examples": [ null ] }, "dataPerBatch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Dataperbatch", "description": "Maximum number of data items to process concurrently within a dataset.", "default": 20, "examples": [ 20 ] } }, "type": "object", "title": "CognifyPayloadDTO" }, "ConfigChoice": { "properties": { "value": { "type": "string", "title": "Value" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "value", "label" ], "title": "ConfigChoice" }, "ConfirmLinkPayload": { "properties": { "code": { "type": "string", "title": "Code" } }, "type": "object", "required": [ "code" ], "title": "ConfirmLinkPayload" }, "ConfirmLinkResultDTO": { "properties": { "linked": { "type": "boolean", "title": "Linked" } }, "type": "object", "required": [ "linked" ], "title": "ConfirmLinkResultDTO" }, "ConnectionStatusDTO": { "properties": { "connected": { "type": "boolean", "title": "Connected" }, "datasetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Datasetid" }, "storedItems": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Storeditems" }, "accountLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accountlabel" }, "providerAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provideraccountid" }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Connectedat" }, "syncStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Syncstatus" }, "lastSyncedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastsyncedat" }, "syncCounts": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Synccounts" } }, "type": "object", "required": [ "connected" ], "title": "ConnectionStatusDTO" }, "CustomPromptGenerationPayloadDTO": { "properties": { "graphModel": { "additionalProperties": true, "type": "object", "title": "Graphmodel", "description": "Graph model schema as JSON object." }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "Additional kwargs forwarded to LLMGateway." } }, "type": "object", "required": [ "graphModel" ], "title": "CustomPromptGenerationPayloadDTO" }, "CustomPromptGenerationResponseDTO": { "properties": { "customPrompt": { "type": "string", "title": "Customprompt" } }, "type": "object", "required": [ "customPrompt" ], "title": "CustomPromptGenerationResponseDTO" }, "DataCountDTO": { "properties": { "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "count" ], "title": "DataCountDTO" }, "DataDTO": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "extension": { "type": "string", "title": "Extension" }, "mimeType": { "type": "string", "title": "Mimetype" }, "rawDataLocation": { "type": "string", "title": "Rawdatalocation" }, "datasetId": { "type": "string", "format": "uuid", "title": "Datasetid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "externalMetadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Externalmetadata" }, "dataSize": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Datasize" } }, "type": "object", "required": [ "id", "name", "extension", "mimeType", "rawDataLocation", "datasetId" ], "title": "DataDTO" }, "DataItemProcessingStatusDTO": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "completed": { "type": "boolean", "title": "Completed" } }, "type": "object", "required": [ "id", "name", "completed" ], "title": "DataItemProcessingStatusDTO", "description": "One data item's completion state for the requested pipeline." }, "DatasetCreationPayload": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the dataset to create. If a dataset with this name already exists for the user, the existing dataset is returned instead of creating a duplicate.", "examples": [ "main_dataset" ] } }, "type": "object", "required": [ "name" ], "title": "DatasetCreationPayload" }, "DatasetDTO": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "ownerId": { "type": "string", "format": "uuid", "title": "Ownerid" } }, "type": "object", "required": [ "id", "name", "createdAt", "ownerId" ], "title": "DatasetDTO" }, "DatasetGraphSummaryDTO": { "properties": { "datasetId": { "type": "string", "format": "uuid", "title": "Datasetid" }, "pipelineRunId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Pipelinerunid" }, "numNodes": { "type": "integer", "title": "Numnodes" }, "numEdges": { "type": "integer", "title": "Numedges" }, "computedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Computedat" } }, "type": "object", "required": [ "datasetId", "numNodes", "numEdges" ], "title": "DatasetGraphSummaryDTO" }, "DatasetProcessingStatusDTO": { "properties": { "total": { "type": "integer", "title": "Total", "description": "Number of data items in the dataset" }, "completed": { "type": "integer", "title": "Completed", "description": "Items carrying the per-item completion stamp" }, "pending": { "type": "integer", "title": "Pending", "description": "Items without the stamp (total - completed)" }, "items": { "items": { "$ref": "#/components/schemas/DataItemProcessingStatusDTO" }, "type": "array", "title": "Items", "description": "One entry per data item, in the same order as GET /datasets/\\{id\\}/data" } }, "type": "object", "required": [ "total", "completed", "pending", "items" ], "title": "DatasetProcessingStatusDTO", "description": "Item-level completion counts for one dataset and one pipeline." }, "DatasetSchemaPayloadDTO": { "properties": { "graphSchema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Graphschema" }, "customPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customprompt" } }, "type": "object", "title": "DatasetSchemaPayloadDTO" }, "DisconnectResultDTO": { "properties": { "disconnected": { "type": "boolean", "title": "Disconnected" } }, "type": "object", "required": [ "disconnected" ], "title": "DisconnectResultDTO" }, "ErrorModel": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" } ], "title": "Detail" } }, "type": "object", "required": [ "detail" ], "title": "ErrorModel" }, "ErrorResponseDTO": { "properties": { "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "ErrorResponseDTO" }, "Fallback": { "properties": { "reason": { "$ref": "#/components/schemas/RefusalReason" }, "detail": { "type": "string", "title": "Detail" } }, "type": "object", "required": [ "reason", "detail" ], "title": "Fallback", "description": "Why the full rebuild ran instead of the chunk-level update." }, "FeedbackEntry": { "properties": { "type": { "type": "string", "const": "feedback", "title": "Type", "default": "feedback" }, "qa_id": { "type": "string", "title": "Qa Id", "description": "entry_id returned by a previous qa remember call \u2014 use it to chain feedback to that QA.", "examples": [ "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f" ] }, "feedback_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback Text" }, "feedback_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feedback Score" } }, "type": "object", "required": [ "qa_id" ], "title": "FeedbackEntry", "description": "Feedback attached to an existing QA entry.\n\nSemantically an update rather than a new memory \u2014 carried through\nremember() for API minimalism. Dispatched to\n``SessionManager.add_feedback``." }, "ForgetPayloadDTO": { "properties": { "dataId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Dataid", "description": "UUID of a single data item to remove. Requires `dataset` or `datasetId` to also be set.", "examples": [ "" ] }, "dataset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset", "description": "Dataset name to delete (or clear with memoryOnly). Provide either `dataset` or `datasetId`, not both.", "examples": [ "default_dataset" ] }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Datasetid", "description": "Dataset UUID, alternative to `dataset`. Provide either `dataset` or `datasetId`, not both.", "examples": [ "" ] }, "everything": { "type": "boolean", "title": "Everything", "description": "DANGER: when true, permanently deletes ALL datasets and data the user owns (relational records, graph, vector embeddings, session cache). Ignores dataId/dataset/datasetId.", "default": false }, "memoryOnly": { "type": "boolean", "title": "Memoryonly", "description": "When True with a dataset, delete only memory (graph nodes/edges and vector embeddings) and reset pipeline status \u2014 raw files and data records are preserved. This allows re-cognifying the dataset from scratch.", "default": false } }, "type": "object", "title": "ForgetPayloadDTO", "examples": [ { "dataset": "main_dataset", "memoryOnly": true } ] }, "Function": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "parameters": { "$ref": "#/components/schemas/FunctionParameters" } }, "type": "object", "required": [ "name", "description", "parameters" ], "title": "Function", "description": "Function definition compatible with OpenAI's format" }, "FunctionCall": { "properties": { "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" } }, "type": "object", "required": [ "name", "arguments" ], "title": "FunctionCall", "description": "Function call made by the assistant" }, "FunctionParameters": { "properties": { "type": { "type": "string", "title": "Type", "default": "object" }, "properties": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object", "title": "Properties" }, "required": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Required" } }, "type": "object", "required": [ "properties" ], "title": "FunctionParameters", "description": "JSON Schema for function parameters" }, "GraphDTO": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/GraphNodeDTO" }, "type": "array", "title": "Nodes" }, "edges": { "items": { "$ref": "#/components/schemas/GraphEdgeDTO" }, "type": "array", "title": "Edges" } }, "type": "object", "required": [ "nodes", "edges" ], "title": "GraphDTO" }, "GraphEdgeDTO": { "properties": { "source": { "type": "string", "format": "uuid", "title": "Source" }, "target": { "type": "string", "format": "uuid", "title": "Target" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "source", "target", "label" ], "title": "GraphEdgeDTO" }, "GraphNodeDTO": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "type": { "type": "string", "title": "Type" }, "properties": { "additionalProperties": true, "type": "object", "title": "Properties" } }, "type": "object", "required": [ "id", "label", "type", "properties" ], "title": "GraphNodeDTO" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ImprovePayloadDTO": { "properties": { "extractionTasks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Extractiontasks", "examples": [ [] ] }, "enrichmentTasks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Enrichmenttasks", "examples": [ [] ] }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data" }, "datasetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Datasetname" }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "const": "" }, { "type": "null" } ], "title": "Datasetid", "examples": [ "" ] }, "nodeName": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Nodename", "examples": [ [] ] }, "runInBackground": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Runinbackground", "default": false }, "buildGlobalContextIndex": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buildglobalcontextindex", "default": false }, "buildTruthSubspace": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buildtruthsubspace", "default": false }, "feedbackAlpha": { "anyOf": [ { "type": "number", "maximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Feedbackalpha" }, "sessionIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sessionids", "examples": [ [] ] } }, "type": "object", "title": "ImprovePayloadDTO" }, "ImproveResult": { "properties": { "dataset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Dataset Id" }, "dataset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Name" }, "session_ids": { "items": { "type": "string" }, "type": "array", "title": "Session Ids" }, "stages": { "items": { "$ref": "#/components/schemas/StageResult" }, "type": "array", "title": "Stages" }, "memify_run": { "title": "Memify Run" }, "background": { "type": "boolean", "title": "Background", "default": false }, "finished": { "type": "boolean", "title": "Finished", "default": true }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "rerun_requested": { "type": "boolean", "title": "Rerun Requested", "default": false }, "rerun_passes": { "items": { "items": { "$ref": "#/components/schemas/StageResult" }, "type": "array" }, "type": "array", "title": "Rerun Passes" }, "status": { "type": "string", "enum": [ "completed", "errored", "skipped", "running" ], "title": "Status", "readOnly": true } }, "type": "object", "required": [ "status" ], "title": "ImproveResult", "description": "One entry per stage, in registry order, for one ``improve()`` run.\n\n``status`` summarises the stages: ``running`` while a background run is\nstill going, ``errored`` when any stage errored, ``skipped`` when every\nstage was skipped (a lost lock claim, an unchanged graph with nothing\nopted in), ``completed`` otherwise. ``await result.wait()`` blocks on a\nbackground run and returns the same, now finished, object." }, "InferSchemaResponseDTO": { "properties": { "graphSchema": { "additionalProperties": true, "type": "object", "title": "Graphschema" } }, "type": "object", "required": [ "graphSchema" ], "title": "InferSchemaResponseDTO" }, "IntegrationResourceDTO": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "attributes": { "additionalProperties": true, "type": "object", "title": "Attributes" }, "selected": { "type": "boolean", "title": "Selected", "default": false } }, "type": "object", "required": [ "id", "name" ], "title": "IntegrationResourceDTO" }, "IntegrationResourceListDTO": { "properties": { "resources": { "items": { "$ref": "#/components/schemas/IntegrationResourceDTO" }, "type": "array", "title": "Resources" }, "selected": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Selected" } }, "type": "object", "required": [ "resources" ], "title": "IntegrationResourceListDTO" }, "IntegrationResourceSelectionPayload": { "properties": { "resourceIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Resourceids" } }, "type": "object", "title": "IntegrationResourceSelectionPayload" }, "IntegrationResourceSelectionResultDTO": { "properties": { "selected": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Selected" } }, "type": "object", "title": "IntegrationResourceSelectionResultDTO" }, "IntegrationStatusItemDTO": { "properties": { "provider": { "type": "string", "title": "Provider" }, "connected": { "type": "boolean", "title": "Connected" }, "accountLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accountlabel" }, "providerAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provideraccountid" }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Connectedat" }, "syncStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Syncstatus" }, "lastSyncedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastsyncedat" }, "syncCounts": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Synccounts" } }, "type": "object", "required": [ "provider", "connected" ], "title": "IntegrationStatusItemDTO" }, "IntegrationSyncResultDTO": { "properties": { "accepted": { "type": "boolean", "title": "Accepted" } }, "type": "object", "required": [ "accepted" ], "title": "IntegrationSyncResultDTO" }, "IntegrationsStatusDTO": { "properties": { "integrations": { "items": { "$ref": "#/components/schemas/IntegrationStatusItemDTO" }, "type": "array", "title": "Integrations" }, "plugins": { "items": { "$ref": "#/components/schemas/PluginStatusItemDTO" }, "type": "array", "title": "Plugins" } }, "type": "object", "required": [ "integrations", "plugins" ], "title": "IntegrationsStatusDTO" }, "IssueSeverity": { "type": "string", "enum": [ "error", "warning" ], "title": "IssueSeverity" }, "IssueType": { "type": "string", "enum": [ "orphaned_edge", "identity_id_mismatch", "missing_vector_entry" ], "title": "IssueType" }, "LLMConfigInputDTO": { "properties": { "provider": { "type": "string", "enum": [ "openai", "ollama", "anthropic", "gemini", "mistral" ], "title": "Provider" }, "model": { "type": "string", "title": "Model" }, "apiKey": { "type": "string", "title": "Apikey" } }, "type": "object", "required": [ "provider", "model", "apiKey" ], "title": "LLMConfigInputDTO" }, "LLMConfigOutputDTO": { "properties": { "apiKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apikey" }, "model": { "type": "string", "title": "Model" }, "provider": { "type": "string", "title": "Provider" }, "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Endpoint" }, "apiVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apiversion" }, "models": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ConfigChoice" }, "type": "array" }, "type": "object", "title": "Models" }, "providers": { "items": { "$ref": "#/components/schemas/ConfigChoice" }, "type": "array", "title": "Providers" } }, "type": "object", "required": [ "apiKey", "model", "provider", "endpoint", "apiVersion", "models", "providers" ], "title": "LLMConfigOutputDTO" }, "MemifyPayloadDTO": { "properties": { "extractionTasks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Extractiontasks", "examples": [ [] ] }, "enrichmentTasks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Enrichmenttasks", "examples": [ [] ] }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data" }, "datasetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Datasetname" }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "const": "" }, { "type": "null" } ], "title": "Datasetid", "examples": [ "" ] }, "nodeName": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Nodename", "examples": [ [] ] }, "runInBackground": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Runinbackground", "default": false } }, "type": "object", "title": "MemifyPayloadDTO" }, "PipelineRunInfo": { "properties": { "status": { "type": "string", "title": "Status" }, "pipeline_run_id": { "type": "string", "format": "uuid", "title": "Pipeline Run Id" }, "dataset_id": { "type": "string", "format": "uuid", "title": "Dataset Id" }, "dataset_name": { "type": "string", "title": "Dataset Name" }, "payload": { "anyOf": [ {}, { "type": "null" } ], "title": "Payload" }, "data_ingestion_info": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Data Ingestion Info" } }, "type": "object", "required": [ "status", "pipeline_run_id", "dataset_id", "dataset_name" ], "title": "PipelineRunInfo" }, "PipelineRunStatus": { "type": "string", "enum": [ "DATASET_PROCESSING_INITIATED", "DATASET_PROCESSING_STARTED", "DATASET_PROCESSING_COMPLETED", "DATASET_PROCESSING_ERRORED" ], "title": "PipelineRunStatus" }, "PipelineRunStatusWithProgress": { "properties": { "status": { "$ref": "#/components/schemas/PipelineRunStatus" }, "progress": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Progress", "examples": [ { "completed_items": 3, "current_stage": "extract_graph", "total_items": 10 } ] } }, "type": "object", "required": [ "status" ], "title": "PipelineRunStatusWithProgress" }, "PluginProvisionDTO": { "properties": { "pluginKey": { "type": "string", "title": "Pluginkey" }, "agentId": { "type": "string", "format": "uuid", "title": "Agentid" }, "apiKey": { "type": "string", "title": "Apikey" }, "created": { "type": "boolean", "title": "Created" } }, "type": "object", "required": [ "pluginKey", "agentId", "apiKey", "created" ], "title": "PluginProvisionDTO" }, "PluginStatusItemDTO": { "properties": { "key": { "type": "string", "title": "Key" }, "connected": { "type": "boolean", "title": "Connected" }, "agentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agentid" }, "provisionedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Provisionedat" }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastactiveat" }, "sessionCount": { "type": "integer", "title": "Sessioncount", "default": 0 }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, "type": "object", "required": [ "key", "connected" ], "title": "PluginStatusItemDTO" }, "ProposalDetail": { "properties": { "proposal_id": { "type": "string", "title": "Proposal Id", "description": "Stable proposal identifier." }, "skill_id": { "type": "string", "title": "Skill Id", "description": "Identifier of the skill being improved.", "default": "" }, "skill_name": { "type": "string", "title": "Skill Name", "description": "Name of the skill being improved.", "default": "" }, "status": { "type": "string", "title": "Status", "description": "Lifecycle status: 'proposed' or 'applied'.", "default": "proposed" }, "confidence": { "type": "number", "title": "Confidence", "description": "Model confidence in the proposed change.", "default": 0.0 }, "rationale": { "type": "string", "title": "Rationale", "description": "Why the change was proposed.", "default": "" }, "model_name": { "type": "string", "title": "Model Name", "description": "LLM that generated the proposal.", "default": "" }, "old_procedure": { "type": "string", "title": "Old Procedure", "description": "Current skill procedure (before).", "default": "" }, "proposed_procedure": { "type": "string", "title": "Proposed Procedure", "description": "Proposed skill procedure (after).", "default": "" }, "runs_used": { "items": { "type": "string" }, "type": "array", "title": "Runs Used", "description": "SkillRun ids whose failures motivated the proposal." }, "dataset_scope": { "items": { "type": "string" }, "type": "array", "title": "Dataset Scope", "description": "Dataset UUIDs this proposal is scoped to." } }, "type": "object", "required": [ "proposal_id" ], "title": "ProposalDetail", "description": "A single skill-improvement proposal, including before/after procedures." }, "QAEntry": { "properties": { "type": { "type": "string", "const": "qa", "title": "Type", "default": "qa" }, "question": { "type": "string", "title": "Question", "examples": [ "What is the capital of France?" ] }, "answer": { "type": "string", "title": "Answer", "examples": [ "The capital of France is Paris." ] }, "context": { "type": "string", "title": "Context", "default": "", "examples": [ "Retrieved from geography_notes.md" ] }, "feedback_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback Text" }, "feedback_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feedback Score" }, "used_graph_element_ids": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Used Graph Element Ids" } }, "type": "object", "required": [ "question", "answer" ], "title": "QAEntry", "description": "A Q&A turn stored in the session cache.\n\nRepresents a user question + assistant answer with optional\nretrieval context. Dispatched to ``SessionManager.add_qa``." }, "RecallHistoryItem": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "user": { "type": "string", "title": "User" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Datasetid" } }, "type": "object", "required": [ "id", "text", "user", "createdAt" ], "title": "RecallHistoryItem" }, "RecallPayloadDTO": { "properties": { "searchType": { "anyOf": [ { "$ref": "#/components/schemas/SearchType" }, { "type": "null" } ], "description": "Search strategy, e.g. HYBRID_COMPLETION, GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS. Omit (or pass null) to let cognee auto-route the query (rule-based, no LLM call, HYBRID_COMPLETION fallback; see docs/recall-vs-search.md for the rule table). Pass a value to pin one." }, "datasets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Datasets", "description": "Dataset names to search within. Omit (null) to search all datasets you have read access to.", "examples": [ [ "default_dataset" ] ] }, "datasetIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Datasetids", "description": "Dataset UUIDs to search within; takes precedence over 'datasets' names when both are provided. Leave empty to resolve by name.", "examples": [ null ] }, "query": { "type": "string", "title": "Query", "description": "The question to answer. Required; there is no default query.", "examples": [ "What is in the document?" ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt", "default": "Answer the question using the provided context. Be as brief as possible." }, "nodeName": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Nodename", "description": "Restrict results to these node sets (the node_set values passed to /v1/add or /v1/remember). Omit to search all nodes.", "examples": [ null ] }, "topK": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Topk", "default": 15 }, "onlyContext": { "type": "boolean", "title": "Onlycontext", "description": "Return what the LLM would have received instead of its answer. For completion search types each item's text is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block) and its system_prompt field carries the retriever's task template. Retrieval-only types return their context. No LLM call is made and nothing is written to the session.", "default": false }, "verbose": { "type": "boolean", "title": "Verbose", "default": false }, "includeReferences": { "type": "boolean", "title": "Includereferences", "description": "Include source/provenance references in completion results.", "default": false }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionid", "description": "Session whose cached QA and trace entries should be searched. With search_type omitted the session becomes a search source: alone it short-circuits the graph on a hit, alongside datasets both contribute. Pinning search_type leaves the graph as the only source.", "examples": [ null ] }, "scope": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scope", "description": "Which memory sources to include: 'graph', 'session', 'session_first', 'trace', 'session_context', 'tools', 'code', 'all', 'auto', or a list of these. Defaults to 'auto' (session first when session_id is set, else graph). 'session_first' asks for that short-circuit explicitly \u2014 a session hit answers alone \u2014 instead of getting it by omitting search_type. 'tools' and 'code' are explicit opt-in only \u2014 never implied by 'auto' or 'all'. 'tools' requires TOOL_CALLS_ENABLED on the server; 'code' runs a deterministic code-graph query (see code_query) and tags results source='code'.", "examples": [ null ] }, "toolConnections": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Toolconnections", "description": "Names of authorized external database connections for the 'tools' scope. Omit to use every connection visible to the caller.", "examples": [ null ] }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stream", "description": "Stream the answer as server-sent events. When omitted, the `Accept` header decides: streaming happens only for a client that ranks `text/event-stream` above `application/json`, so `*/*` and the two listed together both stay on the JSON response." }, "toolsTrigger": { "type": "string", "title": "Toolstrigger", "description": "When the 'tools' scope runs: 'always', or 'on_empty' to query the external database only when every other requested source returned nothing.", "default": "always" }, "codeQuery": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Codequery", "description": "'code' scope only: structured operation and arguments for the deterministic code-graph query (same format as /v1/search code_query, e.g. \\{\"operation\": \"impact_analysis\", \"seeds\": [\"UserService\"]\\}). Omit to run the default 'explore' operation with the query text as seed. A seed the code graph cannot resolve contributes no results rather than failing the recall.", "examples": [ null ] }, "contextProfile": { "type": "string", "title": "Contextprofile", "description": "Profile to render for the 'session_context' scope: 'qa' (conversational) or 'agent' (tool/workflow). Ignored by other scopes.", "default": "qa" }, "responseSchema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Responseschema", "description": "JSON Schema for structured completion output (typically MyModel.model_json_schema()). The completion is validated against it and each result carries the validated payload in its 'structured' field. Supported by completion-style search types only. Structural subset: objects, primitives, arrays, enums, optionals, $defs references; value constraints (minLength, ...) are not enforced server-side.", "examples": [ null ] } }, "type": "object", "required": [ "query" ], "title": "RecallPayloadDTO" }, "RefusalReason": { "type": "string", "enum": [ "disabled", "custom_extraction_config", "per_call_db_config", "unsupported_backend", "unsupported_chunker", "unsupported_metadata", "no_baseline", "chunks_not_tiling", "unreadable_text" ], "title": "RefusalReason", "description": "Why a chunk-level update fell back to the full flow.\n\nEvery refusal used to surface as one free-text message and one log line, so\na permanent misconfiguration (an incompatible chunker, an unsupported\nbackend) looked exactly like a first ingestion. The reason is logged as a\nstructured field and returned in ``UpdateResult.fallback`` so they\nare separable. The first three come from ``update()`` before this engine\nis consulted; the rest are this engine's own refusals." }, "RegisterAgentRequest": { "properties": { "agent_session_name": { "type": "string", "title": "Agent Session Name", "description": "A unique name for this agent connection. Combined with the authenticated user's ID to identify the connection." }, "type": { "type": "string", "title": "Type", "default": "api" }, "memory_mode": { "type": "string", "enum": [ "session", "cognee", "hybrid", "none", "unknown" ], "title": "Memory Mode", "default": "unknown" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "dataset_ids": { "items": { "type": "string" }, "type": "array", "title": "Dataset Ids" }, "dataset_names": { "items": { "type": "string" }, "type": "array", "title": "Dataset Names" }, "source": { "type": "string", "enum": [ "agent_memory", "session_trace", "serve", "api_key", "mcp", "api" ], "title": "Source", "default": "api" }, "origin_function": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Function" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "agent_session_name" ], "title": "RegisterAgentRequest" }, "RememberEntryRequest": { "properties": { "entry": { "oneOf": [ { "$ref": "#/components/schemas/QAEntry" }, { "$ref": "#/components/schemas/TraceEntry" }, { "$ref": "#/components/schemas/FeedbackEntry" }, { "$ref": "#/components/schemas/SkillRunEntry" } ], "title": "Entry", "discriminator": { "propertyName": "type", "mapping": { "feedback": "#/components/schemas/FeedbackEntry", "qa": "#/components/schemas/QAEntry", "skill_run": "#/components/schemas/SkillRunEntry", "trace": "#/components/schemas/TraceEntry" } } }, "dataset_name": { "type": "string", "title": "Dataset Name", "default": "main_dataset" }, "dataset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Dataset Id", "description": "UUID of an existing writable dataset. Takes precedence over dataset_name and is required to target a shared dataset by ID." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id", "description": "Required for qa/trace/feedback entries; optional for skill_run entries.", "examples": [ "claude-code-1718000000" ] }, "self_improvement": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Self Improvement", "description": "Forwarded to remember for compatibility. Typed session entries do not run automatic graph improvement, regardless of this value. This does not control explicit skill_improvement." }, "skill_improvement": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Skill Improvement" } }, "type": "object", "required": [ "entry" ], "title": "RememberEntryRequest", "description": "JSON body for the typed-entry remember endpoint.\n\n``entry`` is a discriminated union \u2014 set ``type`` to ``qa``,\n``trace``, ``feedback``, or ``skill_run`` and include the\ncorresponding fields." }, "ResponseAgentTraceEntry": { "properties": { "trace_id": { "type": "string", "title": "Trace Id" }, "origin_function": { "type": "string", "title": "Origin Function" }, "status": { "type": "string", "title": "Status" }, "memory_query": { "type": "string", "title": "Memory Query", "default": "" }, "memory_context": { "type": "string", "title": "Memory Context", "default": "" }, "method_params": { "additionalProperties": true, "type": "object", "title": "Method Params" }, "method_return_value": { "title": "Method Return Value" }, "error_message": { "type": "string", "title": "Error Message", "default": "" }, "session_feedback": { "type": "string", "title": "Session Feedback", "default": "" }, "source": { "type": "string", "const": "trace", "title": "Source" } }, "type": "object", "required": [ "trace_id", "origin_function", "status", "source" ], "title": "ResponseAgentTraceEntry" }, "ResponseBody": { "properties": { "id": { "type": "string", "title": "Id" }, "created": { "type": "integer", "title": "Created" }, "model": { "type": "string", "title": "Model" }, "object": { "type": "string", "title": "Object", "default": "response" }, "status": { "type": "string", "title": "Status", "default": "completed" }, "toolCalls": { "items": { "$ref": "#/components/schemas/ResponseToolCall" }, "type": "array", "title": "Toolcalls" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ChatUsage" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "model", "toolCalls" ], "title": "ResponseBody", "description": "Response body for the new responses endpoint" }, "ResponseCodeEntry": { "properties": { "kind": { "$ref": "#/components/schemas/SearchResultKind" }, "search_type": { "$ref": "#/components/schemas/SearchType" }, "text": { "type": "string", "title": "Text" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "dataset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Name" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "default": {} }, "raw": { "additionalProperties": true, "type": "object", "title": "Raw", "default": {} }, "structured": { "anyOf": [ {}, { "type": "null" } ], "title": "Structured" }, "source": { "type": "string", "const": "code", "title": "Source" } }, "type": "object", "required": [ "kind", "search_type", "text", "source" ], "title": "ResponseCodeEntry", "description": "One deterministic code-graph fact from the recall \"code\" scope.\n\nSame normalized shape as graph entries (kind CODE, payload under\n``raw``) \u2014 only the source discriminator differs, so callers can\nroute code facts separately from semantic graph results." }, "ResponseGraphEntry": { "properties": { "kind": { "$ref": "#/components/schemas/SearchResultKind" }, "search_type": { "$ref": "#/components/schemas/SearchType" }, "text": { "type": "string", "title": "Text" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "dataset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Name" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "default": {} }, "raw": { "additionalProperties": true, "type": "object", "title": "Raw", "default": {} }, "structured": { "anyOf": [ {}, { "type": "null" } ], "title": "Structured" }, "source": { "type": "string", "const": "graph", "title": "Source" } }, "type": "object", "required": [ "kind", "search_type", "text", "source" ], "title": "ResponseGraphEntry" }, "ResponseMarkerEntry": { "properties": { "source": { "type": "string", "const": "system", "title": "Source" }, "status": { "type": "string", "title": "Status" }, "text": { "type": "string", "title": "Text" }, "datapoint_count": { "type": "integer", "title": "Datapoint Count" }, "threshold": { "type": "integer", "title": "Threshold" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" } }, "type": "object", "required": [ "source", "status", "text", "datapoint_count", "threshold" ], "title": "ResponseMarkerEntry", "description": "System-generated marker (not data), e.g. \"memory still warming up\".\n\n``text`` carries a human-readable message so generic consumers that fall\nback to text rendering display something sensible." }, "ResponseQAEntry": { "properties": { "time": { "type": "string", "title": "Time" }, "question": { "type": "string", "title": "Question" }, "context": { "type": "string", "title": "Context" }, "answer": { "type": "string", "title": "Answer" }, "qa_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Qa Id" }, "feedback_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback Text" }, "feedback_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feedback Score" }, "used_graph_element_ids": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Used Graph Element Ids" }, "memify_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Memify Metadata" }, "used_session_context_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Used Session Context Ids" }, "source": { "type": "string", "const": "session", "title": "Source" } }, "type": "object", "required": [ "time", "question", "context", "answer", "source" ], "title": "ResponseQAEntry" }, "ResponseRequest": { "properties": { "model": { "$ref": "#/components/schemas/CogneeModel", "default": "cognee-v1" }, "input": { "type": "string", "title": "Input" }, "tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ToolFunction" }, "type": "array" }, { "type": "null" } ], "title": "Tools" }, "toolChoice": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Toolchoice", "default": "auto" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "default": 1.0 }, "maxCompletionTokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxcompletiontokens" } }, "type": "object", "required": [ "input" ], "title": "ResponseRequest", "description": "Request body for the new responses endpoint (OpenAI Responses API format)" }, "ResponseSessionContextEntry": { "properties": { "source": { "type": "string", "const": "session_context", "title": "Source" }, "content": { "type": "string", "title": "Content" }, "context_profile": { "type": "string", "title": "Context Profile" } }, "type": "object", "required": [ "source", "content", "context_profile" ], "title": "ResponseSessionContextEntry" }, "ResponseSkillEntry": { "properties": { "source": { "type": "string", "const": "skills", "title": "Source" }, "text": { "type": "string", "title": "Text" }, "skill": { "additionalProperties": true, "type": "object", "title": "Skill" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" } }, "type": "object", "required": [ "source", "text", "skill" ], "title": "ResponseSkillEntry", "description": "One skill surfaced by the deterministic skill gate.\n\nMetadata-only: ``skill`` carries the projected Skill fields and never the\nprocedure body \u2014 progressive disclosure keeps bodies behind the\n``load_skill`` tool or ``GET /skills/{skill_id}``. ``text`` is a\nrenderable \"name: description\" line; ``score`` is the raw vector distance\n(lower is better) when available." }, "ResponseToolCall": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/FunctionCall" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallOutput" }, { "type": "null" } ] } }, "type": "object", "required": [ "function" ], "title": "ResponseToolCall", "description": "Tool call in a response" }, "ResponseToolEntry": { "properties": { "source": { "type": "string", "const": "tools", "title": "Source" }, "tool_name": { "type": "string", "title": "Tool Name" }, "question": { "type": "string", "title": "Question" }, "text": { "type": "string", "title": "Text" }, "success": { "type": "boolean", "title": "Success", "default": true }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "structured": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Structured" } }, "type": "object", "required": [ "source", "tool_name", "question", "text" ], "title": "ResponseToolEntry", "description": "One tool invocation's result from the recall \"tools\" scope.\n\nGeneric across tools: ``tool_name`` discriminates the tool (only\n``text_to_sql`` in v1) and ``structured`` carries the tool-specific\npayload, so adding a tool never changes this union. Secrets (connection\nstrings) never appear here." }, "SchemaInventoryItem": { "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Semantic type name." }, "count": { "type": "integer", "minimum": 0.0, "title": "Count", "description": "Total number of instances of this type." }, "samples": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "array", "title": "Samples", "description": "Representative instance names." }, "sample_size": { "type": "integer", "minimum": 0.0, "title": "Sample Size", "description": "Number of returned samples." }, "relationships": { "items": { "$ref": "#/components/schemas/SchemaInventoryRelationship" }, "type": "array", "title": "Relationships", "description": "Relationship aggregates involving this semantic type." } }, "type": "object", "required": [ "count", "sample_size" ], "title": "SchemaInventoryItem", "description": "Per-semantic-type inventory row returned by /schema/inventory." }, "SchemaInventoryRelationship": { "properties": { "to_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Type", "description": "Target semantic type for this relationship aggregate." }, "relation": { "type": "string", "title": "Relation", "description": "Relationship name." }, "count": { "type": "integer", "minimum": 0.0, "title": "Count", "description": "Number of matching relationships." } }, "type": "object", "required": [ "relation", "count" ], "title": "SchemaInventoryRelationship", "description": "Relationship aggregate from one semantic type to another." }, "SearchHistoryItem": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "text": { "type": "string", "title": "Text" }, "user": { "type": "string", "title": "User" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "datasetId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Datasetid" } }, "type": "object", "required": [ "id", "text", "user", "createdAt" ], "title": "SearchHistoryItem" }, "SearchPayloadDTO": { "properties": { "searchType": { "$ref": "#/components/schemas/SearchType", "description": "Retrieval strategy. Common values: HYBRID_COMPLETION (default, passages + entities + LLM answer), GRAPH_COMPLETION (graph context + LLM answer), CODE (deterministic code graph), RAG_COMPLETION, CHUNKS, SUMMARIES, TEMPORAL, FEELING_LUCKY (auto-select), AGENTIC_COMPLETION (enables skills/tools/max_iter).", "default": "HYBRID_COMPLETION" }, "datasets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Datasets", "description": "Dataset names to search. Names only resolve to datasets owned by the caller; use dataset_ids for datasets shared with you.", "examples": [ [ "default_dataset" ] ] }, "datasetIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Datasetids", "description": "Dataset UUIDs to search (required for datasets shared with you). When provided, the datasets name list is ignored.", "examples": [ null ] }, "query": { "type": "string", "title": "Query", "description": "The question to answer. Required; there is no default query.", "examples": [ "What is in the document?" ] }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt", "default": "Answer the question using the provided context. Be as brief as possible." }, "nodeName": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Nodename", "description": "Restrict results to nodes in these node_sets (the node_set values used during add/remember).", "examples": [ null ] }, "topK": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Topk", "default": 15 }, "onlyContext": { "type": "boolean", "title": "Onlycontext", "description": "Return what the LLM would have received instead of its answer. For completion search types the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is system_prompt_result with verbose=true. The session layer comes from session_id (the default session when omitted). Retrieval-only types return their context. No LLM call is made and nothing is written to the session.", "default": false }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionid", "description": "Session whose history and guidance feed the completion (or the only_context prompt). Omit to use the default session.", "examples": [ null ] }, "verbose": { "type": "boolean", "title": "Verbose", "description": "Return detailed result information including the graph representation when available.", "default": false }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills", "description": "Skill names to load into the agentic retriever. Requires search_type=AGENTIC_COMPLETION; leave null otherwise.", "examples": [ null ] }, "tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "Whitelist of tool names available to the agentic retriever. Requires search_type=AGENTIC_COMPLETION.", "examples": [ null ] }, "maxIter": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxiter", "description": "Maximum agentic tool-call iterations before forcing a final answer (positive integer; AGENTIC_COMPLETION only).", "examples": [ null ] }, "includeReferences": { "type": "boolean", "title": "Includereferences", "description": "Attach source references to completion-type results.", "default": false }, "codeQuery": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Codequery", "description": "Structured arguments for search_type=CODE. Set operation to query_facts, explore, traverse, find_path, impact_analysis, insights, architecture, or delta. Add diagram='mermaid' (or 'dot', or true) to receive the result rendered as diagram source under search_result[0].diagram; architecture includes a Mermaid diagram unless diagram=false." } }, "type": "object", "required": [ "query" ], "title": "SearchPayloadDTO" }, "SearchResult": { "properties": { "search_result": { "title": "Search Result" }, "dataset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Dataset Id" }, "dataset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Name" } }, "type": "object", "required": [ "search_result", "dataset_id", "dataset_name" ], "title": "SearchResult" }, "SearchResultKind": { "type": "string", "enum": [ "graph_completion", "rag_completion", "triplet_completion", "cypher", "chunk", "summary", "coding_rule", "code", "skill", "natural_language", "temporal", "structured", "unknown" ], "title": "SearchResultKind", "description": "Semantic kind of a search result item.\n\nMore precise than ``search_type`` alone \u2014 tells the caller which\nnormalization shape was applied. LLM completion types all collapse\nto ``*_COMPLETION`` kinds; non-LLM retrievers produce structural\nkinds (``CHUNK``, ``SUMMARY``, ``CYPHER`` row)." }, "SearchType": { "type": "string", "enum": [ "SUMMARIES", "CHUNKS", "RAG_COMPLETION", "HYBRID_COMPLETION", "TRIPLET_COMPLETION", "GRAPH_COMPLETION", "GRAPH_COMPLETION_DECOMPOSITION", "GRAPH_SUMMARY_COMPLETION", "CYPHER", "NATURAL_LANGUAGE", "GRAPH_COMPLETION_COT", "GRAPH_COMPLETION_CONTEXT_EXTENSION", "FEELING_LUCKY", "TEMPORAL", "CODING_RULES", "CHUNKS_LEXICAL", "AGENTIC_COMPLETION", "CODE", "GRAPH_REPORT", "SKILLS" ], "title": "SearchType" }, "SelectTenantDTO": { "properties": { "tenantId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Tenantid" } }, "type": "object", "title": "SelectTenantDTO" }, "SetAllowedChannelsPayload": { "properties": { "channelIds": { "items": { "type": "string" }, "type": "array", "title": "Channelids" } }, "type": "object", "required": [ "channelIds" ], "title": "SetAllowedChannelsPayload" }, "SetAllowedChannelsResultDTO": { "properties": { "allowedChannelIds": { "items": { "type": "string" }, "type": "array", "title": "Allowedchannelids" } }, "type": "object", "required": [ "allowedChannelIds" ], "title": "SetAllowedChannelsResultDTO" }, "SettingsDTO": { "properties": { "llm": { "$ref": "#/components/schemas/LLMConfigOutputDTO" }, "vectorDb": { "$ref": "#/components/schemas/VectorDBConfigOutputDTO" } }, "type": "object", "required": [ "llm", "vectorDb" ], "title": "SettingsDTO" }, "SettingsPayloadDTO": { "properties": { "llm": { "anyOf": [ { "$ref": "#/components/schemas/LLMConfigInputDTO" }, { "type": "null" } ] }, "vectorDb": { "anyOf": [ { "$ref": "#/components/schemas/VectorDBConfigInputDTO" }, { "type": "null" } ] } }, "type": "object", "title": "SettingsPayloadDTO" }, "SkillDetail": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable skill identifier." }, "name": { "type": "string", "title": "Name", "description": "Skill name." }, "description": { "type": "string", "title": "Description", "description": "Short summary for routing.", "default": "" }, "maintainer": { "type": "string", "title": "Maintainer", "description": "Publishing company / team that maintains the skill.", "default": "" }, "maintainer_url": { "type": "string", "title": "Maintainer Url", "description": "Maintainer homepage or repo URL.", "default": "" }, "version": { "type": "string", "title": "Version", "description": "Skill version string.", "default": "" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Free-form category tags." }, "license": { "type": "string", "title": "License", "description": "License identifier.", "default": "" }, "declared_tools": { "items": { "type": "string" }, "type": "array", "title": "Declared Tools", "description": "Tools the skill is allowed to use." }, "dataset_scope": { "items": { "type": "string" }, "type": "array", "title": "Dataset Scope", "description": "Dataset UUIDs this skill is scoped to." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the skill is active for routing.", "default": true }, "source_repo_url": { "type": "string", "title": "Source Repo Url", "description": "Source repository URL, when known.", "default": "" }, "source_dir": { "type": "string", "title": "Source Dir", "description": "On-disk source directory.", "default": "" }, "procedure": { "type": "string", "title": "Procedure", "description": "The full skill instruction body.", "default": "" } }, "type": "object", "required": [ "id", "name" ], "title": "SkillDetail", "description": "A single skill including its full procedure body." }, "SkillIngestRequest": { "properties": { "skills_text": { "type": "string", "title": "Skills Text", "description": "Inline SKILL.md markdown to ingest as a Skill node." }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name", "description": "Name/slug for the skill (defaults to 'skill')." }, "dataset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Name", "description": "Target dataset name (created if needed). Required unless dataset_id is given." }, "dataset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Dataset Id", "description": "Target dataset UUID (alternative to dataset_name)." } }, "type": "object", "required": [ "skills_text" ], "title": "SkillIngestRequest", "description": "JSON body for ingesting a single skill from inline SKILL.md markdown." }, "SkillListItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable skill identifier." }, "name": { "type": "string", "title": "Name", "description": "Skill name." }, "description": { "type": "string", "title": "Description", "description": "Short summary for routing.", "default": "" }, "maintainer": { "type": "string", "title": "Maintainer", "description": "Publishing company / team that maintains the skill.", "default": "" }, "maintainer_url": { "type": "string", "title": "Maintainer Url", "description": "Maintainer homepage or repo URL.", "default": "" }, "version": { "type": "string", "title": "Version", "description": "Skill version string.", "default": "" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Free-form category tags." }, "license": { "type": "string", "title": "License", "description": "License identifier.", "default": "" }, "declared_tools": { "items": { "type": "string" }, "type": "array", "title": "Declared Tools", "description": "Tools the skill is allowed to use." }, "dataset_scope": { "items": { "type": "string" }, "type": "array", "title": "Dataset Scope", "description": "Dataset UUIDs this skill is scoped to." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the skill is active for routing.", "default": true }, "source_repo_url": { "type": "string", "title": "Source Repo Url", "description": "Source repository URL, when known.", "default": "" }, "source_dir": { "type": "string", "title": "Source Dir", "description": "On-disk source directory.", "default": "" } }, "type": "object", "required": [ "id", "name" ], "title": "SkillListItem", "description": "One skill row returned by GET /skills." }, "SkillRunEntry": { "properties": { "type": { "type": "string", "const": "skill_run", "title": "Type", "default": "skill_run" }, "run_id": { "type": "string", "title": "Run Id" }, "selected_skill_id": { "type": "string", "title": "Selected Skill Id" }, "task_text": { "type": "string", "title": "Task Text", "default": "" }, "result_summary": { "type": "string", "title": "Result Summary", "default": "" }, "success_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Success Score" }, "feedback": { "type": "number", "title": "Feedback", "default": 0.0 }, "error_type": { "type": "string", "title": "Error Type", "default": "" }, "error_message": { "type": "string", "title": "Error Message", "default": "" }, "started_at_ms": { "type": "integer", "title": "Started At Ms", "default": 0 }, "latency_ms": { "type": "integer", "title": "Latency Ms", "default": 0 }, "candidate_skill_ids": { "items": { "type": "string" }, "type": "array", "title": "Candidate Skill Ids" }, "task_pattern_id": { "type": "string", "title": "Task Pattern Id", "default": "" }, "router_version": { "type": "string", "title": "Router Version", "default": "" }, "tool_trace": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Tool Trace" }, "node_set": { "type": "string", "title": "Node Set", "default": "skills" } }, "type": "object", "required": [ "selected_skill_id" ], "title": "SkillRunEntry", "description": "A persisted execution record for a skill.\n\nThis is graph-backed rather than session-cache-backed. It lets agents\nreport explicit skill quality signals through ``cognee.remember()``\nwithout adding another public API surface." }, "SlackHistoryRequest": { "properties": { "dataset_id": { "type": "string", "format": "uuid", "title": "Dataset Id" }, "channel_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "title": "Channel Ids" }, "thread_links": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "title": "Thread Links" }, "threads": { "items": { "$ref": "#/components/schemas/SlackThread" }, "type": "array", "maxItems": 50, "title": "Threads" }, "days": { "anyOf": [ { "type": "integer", "maximum": 3650.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Days" }, "oldest": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Oldest" }, "latest": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest" }, "thread_mode": { "type": "string", "enum": [ "started", "active" ], "title": "Thread Mode", "default": "started" }, "max_requests": { "type": "integer", "maximum": 10000.0, "minimum": 1.0, "title": "Max Requests", "default": 1000 }, "max_messages": { "type": "integer", "maximum": 500000.0, "minimum": 1.0, "title": "Max Messages", "default": 50000 } }, "additionalProperties": false, "type": "object", "required": [ "dataset_id" ], "title": "SlackHistoryRequest", "description": "Date bounds select conversations; selected threads include all available replies.\n\n``started`` selects roots in the window. ``active`` also scans older roots\nand selects threads with a message in the window. Neither is a retention\npolicy. Explicit thread links select entire conversations independently\nof the date window. All bounds are timezone-aware." }, "SlackHistoryResult": { "properties": { "dataset_id": { "type": "string", "format": "uuid", "title": "Dataset Id" }, "conversations": { "type": "integer", "title": "Conversations", "default": 0 }, "messages": { "type": "integer", "title": "Messages", "default": 0 }, "added": { "type": "integer", "title": "Added", "default": 0 }, "updated": { "type": "integer", "title": "Updated", "default": 0 }, "unchanged": { "type": "integer", "title": "Unchanged", "default": 0 }, "deleted": { "type": "integer", "title": "Deleted", "default": 0 }, "status": { "type": "string", "const": "completed", "title": "Status", "default": "completed" } }, "type": "object", "required": [ "dataset_id" ], "title": "SlackHistoryResult" }, "SlackSyncSettings": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "default": false }, "selection": { "anyOf": [ { "$ref": "#/components/schemas/SlackHistoryRequest" }, { "type": "null" } ] }, "interval_seconds": { "type": "integer", "maximum": 604800.0, "minimum": 600.0, "title": "Interval Seconds", "default": 21600 } }, "additionalProperties": false, "type": "object", "title": "SlackSyncSettings" }, "SlackThread": { "properties": { "channel_id": { "type": "string", "pattern": "^[CG][A-Z0-9]+$", "title": "Channel Id" }, "ts": { "type": "string", "pattern": "^\\d{10,}\\.\\d{6}$", "title": "Ts" } }, "additionalProperties": false, "type": "object", "required": [ "channel_id", "ts" ], "title": "SlackThread" }, "StageResult": { "properties": { "stage": { "type": "string", "title": "Stage" }, "status": { "type": "string", "enum": [ "completed", "already_completed", "skipped", "errored" ], "title": "Status" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Counts" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 }, "run": { "anyOf": [ { "$ref": "#/components/schemas/PipelineRunInfo" }, { "type": "null" } ] } }, "type": "object", "required": [ "stage", "status" ], "title": "StageResult", "description": "What one stage did in one run." }, "StorePrincipalConfigurationPayloadDTO": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the configuration to store. If a configuration with this name already exists for the user it is updated in place. Always provide a value: omitting it results in a server error.", "examples": [ "default_llm_settings" ] }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "The configuration data to store as a JSON object (e.g. a KG schema, LLM settings, or ingestion parameters). Always provide a value: omitting it results in a server error.", "examples": [ { "chunk_size": 4096, "llm_model": "openai/gpt-4o-mini" } ] } }, "type": "object", "title": "StorePrincipalConfigurationPayloadDTO" }, "SyncRequest": { "properties": { "datasetIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Datasetids" } }, "type": "object", "title": "SyncRequest", "description": "Request model for sync operations." }, "SyncResponse": { "properties": { "run_id": { "type": "string", "title": "Run Id" }, "status": { "type": "string", "title": "Status" }, "dataset_ids": { "items": { "type": "string" }, "type": "array", "title": "Dataset Ids" }, "dataset_names": { "items": { "type": "string" }, "type": "array", "title": "Dataset Names" }, "message": { "type": "string", "title": "Message" }, "timestamp": { "type": "string", "title": "Timestamp" }, "user_id": { "type": "string", "title": "User Id" } }, "type": "object", "required": [ "run_id", "status", "dataset_ids", "dataset_names", "message", "timestamp", "user_id" ], "title": "SyncResponse", "description": "Response model for sync operations." }, "ToolCallOutput": { "properties": { "status": { "type": "string", "title": "Status", "default": "success" }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Data" } }, "type": "object", "title": "ToolCallOutput", "description": "Output of a tool call in the responses API" }, "ToolFunction": { "properties": { "type": { "type": "string", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/Function" } }, "type": "object", "required": [ "function" ], "title": "ToolFunction", "description": "Tool function wrapper (for OpenAI compatibility)" }, "TraceEntry": { "properties": { "type": { "type": "string", "const": "trace", "title": "Type", "default": "trace" }, "origin_function": { "type": "string", "title": "Origin Function", "description": "Name of the tool/function whose execution this trace step records.", "examples": [ "search_codebase" ] }, "status": { "type": "string", "enum": [ "success", "error" ], "title": "Status", "default": "success" }, "method_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Method Params" }, "method_return_value": { "anyOf": [ {}, { "type": "null" } ], "title": "Method Return Value" }, "memory_query": { "type": "string", "title": "Memory Query", "default": "" }, "memory_context": { "type": "string", "title": "Memory Context", "default": "" }, "error_message": { "type": "string", "title": "Error Message", "default": "" }, "generate_feedback_with_llm": { "type": "boolean", "title": "Generate Feedback With Llm", "default": false } }, "type": "object", "required": [ "origin_function" ], "title": "TraceEntry", "description": "One step of an agent trace.\n\nStructured representation of a tool/function call \u2014 origin,\noutcome, parameters, return value. Dispatched to\n``SessionManager.add_agent_trace_step``." }, "UnregisterAgentRequest": { "properties": { "agent_session_name": { "type": "string", "title": "Agent Session Name", "description": "The name used when registering the connection. Combined with the authenticated user's ID to identify which connection to deactivate." } }, "type": "object", "required": [ "agent_session_name" ], "title": "UnregisterAgentRequest" }, "UpdateError": { "properties": { "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "title": "UpdateError", "description": "Why the rebuild's cognify run failed." }, "UpdateResult": { "properties": { "status": { "type": "string", "enum": [ "incremental", "unchanged", "full_rebuild", "failed" ], "title": "Status" }, "regions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Regions" }, "deleted_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Deleted Chunks" }, "added_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Added Chunks" }, "reused_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reused Chunks" }, "kept_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Kept Chunks" }, "reindexed_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reindexed Chunks" }, "total_chunks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Chunks" }, "data_id": { "type": "string", "format": "uuid", "title": "Data Id" }, "dataset_id": { "type": "string", "format": "uuid", "title": "Dataset Id" }, "duration_seconds": { "type": "number", "title": "Duration Seconds" }, "pipeline_run_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Pipeline Run Id" }, "fallback": { "anyOf": [ { "$ref": "#/components/schemas/Fallback" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/UpdateError" }, { "type": "null" } ] } }, "type": "object", "required": [ "status", "data_id", "dataset_id", "duration_seconds" ], "title": "UpdateResult", "description": "Per-document outcome of ``update()``.\n\n``status`` says what happened: the chunk-level path replaced chunks\n(``incremental``) or found nothing to change (``unchanged``), the whole\ndocument was rebuilt (``full_rebuild``), or the rebuild's cognify run\nerrored (``failed``, with ``error`` naming the cause so the call can be\nretried). A rebuild always carries ``fallback``, naming why the chunk-level\npath did not run or that the caller switched it off, and\n``duration_seconds`` makes a slow update visible next to its reason.\n\nThe chunk counters are work done by the chunk-level path \u2014 ``added`` can\nexceed the net change when a re-cut chunk with unchanged content is\nre-extracted in place \u2014 and ``total_chunks`` is the count after the\nupdate. They are ``None`` on a rebuild, which has no diff. The document\nkeeps its ``data_id`` on every path." }, "UserCreate": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "default": true }, "is_superuser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Superuser", "default": false }, "is_verified": { "type": "boolean", "title": "Is Verified", "default": true }, "parent_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent User Id" } }, "type": "object", "required": [ "email", "password" ], "title": "UserCreate" }, "UserDatasetPair": { "properties": { "user_id": { "type": "string", "format": "uuid", "title": "User Id", "description": "UUID of the user who owns the dataset (superuser-only endpoint; obtain via the permissions/users APIs).", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "dataset_id": { "type": "string", "format": "uuid", "title": "Dataset Id", "description": "UUID of the dataset to include in the combined visualization (must be readable by user_id).", "examples": [ "7c9e6679-7425-40de-944b-e07fc1f90ae7" ] } }, "type": "object", "required": [ "user_id", "dataset_id" ], "title": "UserDatasetPair" }, "UserEmailRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "UserEmailRequest" }, "UserRead": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "email": { "type": "string", "format": "email", "title": "Email" }, "is_active": { "type": "boolean", "title": "Is Active", "default": true }, "is_superuser": { "type": "boolean", "title": "Is Superuser", "default": false }, "is_verified": { "type": "boolean", "title": "Is Verified", "default": false }, "tenant_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Tenant Id" }, "parent_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent User Id" } }, "type": "object", "required": [ "id", "email" ], "title": "UserRead" }, "UserUpdate": { "properties": { "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "is_superuser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Superuser" }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Verified" } }, "type": "object", "title": "UserUpdate" }, "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" }, "ValidationIssue": { "properties": { "severity": { "$ref": "#/components/schemas/IssueSeverity" }, "type": { "$ref": "#/components/schemas/IssueType" }, "detail": { "type": "string", "title": "Detail" } }, "type": "object", "required": [ "severity", "type", "detail" ], "title": "ValidationIssue" }, "ValidationReport": { "properties": { "status": { "$ref": "#/components/schemas/ValidationStatus" }, "summary": { "additionalProperties": true, "type": "object", "title": "Summary" }, "issues": { "items": { "$ref": "#/components/schemas/ValidationIssue" }, "type": "array", "title": "Issues" } }, "type": "object", "required": [ "status", "summary", "issues" ], "title": "ValidationReport" }, "ValidationStatus": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy" ], "title": "ValidationStatus" }, "VectorDBConfigInputDTO": { "properties": { "provider": { "type": "string", "enum": [ "lancedb", "pgvector" ], "title": "Provider" }, "url": { "type": "string", "title": "Url" }, "apiKey": { "type": "string", "title": "Apikey" } }, "type": "object", "required": [ "provider", "url", "apiKey" ], "title": "VectorDBConfigInputDTO" }, "VectorDBConfigOutputDTO": { "properties": { "apiKey": { "type": "string", "title": "Apikey" }, "url": { "type": "string", "title": "Url" }, "provider": { "type": "string", "title": "Provider" }, "providers": { "items": { "$ref": "#/components/schemas/ConfigChoice" }, "type": "array", "title": "Providers" } }, "type": "object", "required": [ "apiKey", "url", "provider", "providers" ], "title": "VectorDBConfigOutputDTO" }, "cognee__api__DTO__ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Error body returned by routers that answer 4xx/5xx themselves.\n\n``error`` is the human-readable message. Errors raised as ``CogneeApiError`` are\nrendered instead by the app-level handler in ``cognee/api/client.py`` as\n``{\"detail\": \" []\"}`` plus ``\"remediation\"`` when a fix is known." }, "cognee__api__v1__proposals__routers__get_proposals_router__ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Generic API error response." }, "cognee__api__v1__skills__routers__get_skills_router__ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Generic API error response." }, "cognee__api__v1__visualize__routers__get_schema_router__ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Generic API error response." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "auth_token" } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "servers": [ { "url": "https://{tenant}.aws.cognee.ai", "description": "Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard", "variables": { "tenant": { "default": "your-tenant", "description": "Your tenant name, shown in the Cognee Cloud dashboard" } } }, { "url": "http://localhost:8000", "description": "Self-hosted: a locally running cognee server" } ], "tags": [ { "name": "activity", "description": "Activity endpoints for inspecting pipeline runs, traced spans, tenant users, agents, and dataset exports." }, { "name": "add", "description": "Data ingestion endpoints for adding text, files, and structured data." }, { "name": "agent connections", "description": "Endpoints for registering, unregistering, and inspecting agent connections to the instance." }, { "name": "agent management", "description": "Endpoints for creating, listing, retrieving, and deleting agents." }, { "name": "auth", "description": "Authentication endpoints for user registration, login, and token management." }, { "name": "checks", "description": "Diagnostic endpoint for validating a Cognee Cloud API key supplied in the X-Api-Key header." }, { "name": "cognify", "description": "Knowledge processing endpoints to transform raw data into knowledge graphs." }, { "name": "configuration", "description": "Endpoints for storing, retrieving, and listing a user's saved configurations." }, { "name": "datasets", "description": "Dataset management endpoints for listing, creating, and deleting datasets." }, { "name": "delete", "description": "Data deletion endpoints (deprecated \u2014 use datasets endpoints instead)." }, { "name": "forget", "description": "Endpoint for removing data from the knowledge graph." }, { "name": "health", "description": "Liveness, readiness, and component health checks." }, { "name": "improve", "description": "Endpoint for enriching and improving an existing knowledge graph." }, { "name": "integrations", "description": "Endpoints for connecting, provisioning, and disconnecting OAuth providers and plugins." }, { "name": "llm", "description": "LLM-backed endpoints for inferring graph schemas and generating custom extraction prompts." }, { "name": "memify", "description": "Endpoint for running enrichment pipelines over existing graphs or supplied data." }, { "name": "ontologies", "description": "Endpoints for uploading, listing, and deleting ontology files used during cognify." }, { "name": "permissions", "description": "Permission management for multi-user access control." }, { "name": "recall", "description": "Endpoints for querying the knowledge graph and reviewing past recall history." }, { "name": "remember", "description": "Endpoints for ingesting data into the knowledge graph and storing session memory entries." }, { "name": "responses", "description": "Response generation endpoints using the knowledge graph." }, { "name": "schema", "description": "Schema inspection endpoints for a dataset's derived schema inventory and the caller-wide memory provenance graph." }, { "name": "search", "description": "Search endpoints for querying the knowledge graph." }, { "name": "sessions", "description": "Endpoints for listing sessions and reporting usage, cost, and token statistics." }, { "name": "settings", "description": "Configuration endpoints for managing Cognee settings." }, { "name": "skills", "description": "Skill management endpoints for ingesting, listing, retrieving, and deleting dataset skills, plus read-only retrieval of improvement proposals." }, { "name": "slack", "description": "Endpoints for listing workspace channels, setting channel allowlists, and linking Slack accounts." }, { "name": "sync", "description": "Endpoints for syncing local data to Cognee Cloud and checking sync status." }, { "name": "update", "description": "Endpoint for updating existing data in a dataset." }, { "name": "users", "description": "User management endpoints." }, { "name": "validate", "description": "Diagnostic endpoint for checking consistency between a dataset's graph and vector stores." }, { "name": "visualize", "description": "Graph visualization endpoints." } ] }