add

Add

Add data to a dataset for processing and knowledge graph construction.

This endpoint accepts various types of data (files, URLs, GitHub repositories) and adds them to a specified dataset for processing. The data is ingested, analyzed, and integrated into the knowledge graph.

Request Parameters

data (List[UploadFile]): List of files to upload. Can also include:
- HTTP URLs (if ALLOW_HTTP_REQUESTS is enabled)
- GitHub repository URLs (will be cloned and processed)
- CSV files (auto-detected as structured data via dlt integration)
- Regular file uploads
datasetName (Optional[str]): Name of the dataset to add data to
datasetId (Optional[UUID]): UUID of an already existing dataset
node_set Optional[list[str]]: List of node identifiers for graph organization and access control. Used for grouping related data points in the knowledge graph.

Either datasetName or datasetId must be provided.

Structured Data (dlt)

CSV files uploaded through this endpoint are automatically detected and processed via the dlt (data load tool) integration. Structured data is ingested deterministically — foreign key relationships become graph edges, and no LLM extraction is needed. For full programmatic control over dlt resources, database connections, write dispositions, and primary keys, use the Python SDK (cognee.add()).

Response

Returns information about the add operation containing:

Status of the operation
Details about the processed data
Any relevant metadata from the ingestion process

Error Codes

400 Bad Request: Neither datasetId nor datasetName provided
409 Conflict: Error during add operation
403 Forbidden: User doesn’t have permission to add to dataset

Notes

To add data to datasets not owned by the user, use dataset_id (when ENABLE_BACKEND_ACCESS_CONTROL is set to True)
datasetId value can only be the UUID of an already existing dataset

POST

/

api

/

v1

/

add

Add

curl --request POST \
  --url https://api.cognee.ai/api/v1/add \
  --header 'Content-Type: multipart/form-data' \
  --form 'data=Cognee is a knowledge graph platform for AI applications.'

{}

Body

multipart/form-data

data

string[]

datasetName

string | null

datasetId

Example:

""

node_set

string[] | null

Response

Successful Response

The response is of type Response Add Api V1 Add Post · object.

CognifyTransform 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). - **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. - **ontology_key** (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction. ## 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, or when specified datasets don't exist - **409 Conflict**: When processing fails due to system errors, missing LLM API keys, database connection failures, or corrupted content ## 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.

⌘I

Add

curl --request POST \
  --url https://api.cognee.ai/api/v1/add \
  --header 'Content-Type: multipart/form-data' \
  --form 'data=Cognee is a knowledge graph platform for AI applications.'

{}