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)
- Regular file uploads
datasetName (Optional[str]): Name of the dataset to add data to
datasetId (Optional[UUID]): UUID of an already existing dataset

Either datasetName or datasetId must be provided.

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)
GitHub repositories are cloned and all files are processed
HTTP URLs are fetched and their content is processed
The ALLOW_HTTP_REQUESTS environment variable controls URL processing
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=<string>' \
  --form 'datasetName=<string>' \
  --form datasetId= \
  --form data.items='@example-file'

{}

Body

multipart/form-data

data

file[]

List of files to upload (max 10MB per file, max 10 files)

Maximum array length: 10

Maximum string length: 10485760

datasetName

string | null

datasetId

Example:

""

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). ## 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 } ``` ## 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=<string>' \
  --form 'datasetName=<string>' \
  --form datasetId= \
  --form data.items='@example-file'

{}