> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cognify (low level): build the knowledge graph from already-added data > Transform datasets into structured knowledge graphs through cognitive processing. This endpoint is the core of Cognee's intelligence layer, responsible for converting raw text, documents, and data added through the add endpoint into semantic knowledge graphs. It performs deep analysis to extract entities, relationships, and insights from ingested content. ## Processing Pipeline 1. Document classification and permission validation 2. Text chunking and semantic segmentation 3. Entity extraction using LLM-powered analysis 4. Relationship detection and graph construction 5. Vector embeddings generation for semantic search 6. Content summarization and indexing ## Request Parameters - **datasets** (Optional[List[str]]): List of dataset names to process. Dataset names are resolved to datasets owned by the authenticated user. - **dataset_ids** (Optional[List[UUID]]): List of existing dataset UUIDs to process. UUIDs allow processing of datasets not owned by the user (if permitted). - **run_in_background** (Optional[bool]): Whether to execute processing asynchronously. Defaults to False (blocking). - **graph_model** (Optional[dict]): JSON schema describing a custom graph model for entity extraction. When omitted or \{\}, the default KnowledgeGraph model is used. - **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. - **chunk_size** (Optional[int]): Maximum tokens per chunk. If omitted, Cognee chooses a size from the configured LLM and embedding limits. - **ontology_key** (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction. - **chunks_per_batch** (Optional[int]): Number of chunks to process per task batch in Cognify. Uses the pipeline default when omitted. - **data_per_batch** (Optional[int]): Maximum number of data items to process concurrently within a dataset. Defaults to 20. ## Response - **Blocking execution**: Complete pipeline run information with entity counts, processing duration, and success/failure status - **Background execution**: Pipeline run metadata including pipeline_run_id for status monitoring via WebSocket subscription ## Error Codes - **400 Bad Request**: When neither datasets nor dataset_ids are provided - **409 Conflict**: When a referenced ontology_key does not exist - **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) ## Example Request ```json { "datasets": ["research_papers", "documentation"], "run_in_background": false, "custom_prompt": "Extract entities focusing on technical concepts and their relationships. Identify key technologies, methodologies, and their interconnections.", "ontology_key": ["medical_ontology_v1"] } ``` ## Notes To cognify data in datasets not owned by the user and for which the current user has write permission, the dataset_id must be used (when ENABLE_BACKEND_ACCESS_CONTROL is set to True). ## Next Steps After successful processing, use the search endpoints to query the generated knowledge graph for insights, relationships, and semantic search. ## OpenAPI ````yaml /cognee_openapi_spec.json post /api/v1/cognify openapi: 3.1.0 info: title: Cognee API description: Cognee API with Bearer token and Cookie auth version: 1.0.0 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' security: - BearerAuth: [] - ApiKeyAuth: [] 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 — 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. paths: /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. This endpoint is the core of Cognee's intelligence layer, responsible for converting raw text, documents, and data added through the add endpoint into semantic knowledge graphs. It performs deep analysis to extract entities, relationships, and insights from ingested content. ## Processing Pipeline 1. Document classification and permission validation 2. Text chunking and semantic segmentation 3. Entity extraction using LLM-powered analysis 4. Relationship detection and graph construction 5. Vector embeddings generation for semantic search 6. Content summarization and indexing ## Request Parameters - **datasets** (Optional[List[str]]): List of dataset names to process. Dataset names are resolved to datasets owned by the authenticated user. - **dataset_ids** (Optional[List[UUID]]): List of existing dataset UUIDs to process. UUIDs allow processing of datasets not owned by the user (if permitted). - **run_in_background** (Optional[bool]): Whether to execute processing asynchronously. Defaults to False (blocking). - **graph_model** (Optional[dict]): JSON schema describing a custom graph model for entity extraction. When omitted or \{\}, the default KnowledgeGraph model is used. - **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. - **chunk_size** (Optional[int]): Maximum tokens per chunk. If omitted, Cognee chooses a size from the configured LLM and embedding limits. - **ontology_key** (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction. - **chunks_per_batch** (Optional[int]): Number of chunks to process per task batch in Cognify. Uses the pipeline default when omitted. - **data_per_batch** (Optional[int]): Maximum number of data items to process concurrently within a dataset. Defaults to 20. ## Response - **Blocking execution**: Complete pipeline run information with entity counts, processing duration, and success/failure status - **Background execution**: Pipeline run metadata including pipeline_run_id for status monitoring via WebSocket subscription ## Error Codes - **400 Bad Request**: When neither datasets nor dataset_ids are provided - **409 Conflict**: When a referenced ontology_key does not exist - **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) ## Example Request ```json { "datasets": ["research_papers", "documentation"], "run_in_background": false, "custom_prompt": "Extract entities focusing on technical concepts and their relationships. Identify key technologies, methodologies, and their interconnections.", "ontology_key": ["medical_ontology_v1"] } ``` ## Notes To cognify data in datasets not owned by the user and for which the current user has write permission, the dataset_id must be used (when ENABLE_BACKEND_ACCESS_CONTROL is set to True). ## Next Steps After 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: [] components: schemas: 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 — 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 — 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 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 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. ``error`` is the human-readable message. Errors raised as ``CogneeApiError`` are rendered instead by the app-level handler in ``cognee/api/client.py`` as ``{"detail": " []"}`` plus ``"remediation"`` when a fix is known. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````