add

Add (low level): ingest files, text or URLs into a dataset without building the graph

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

This endpoint accepts file uploads and string inputs (text, server-side file paths, web URLs, GitHub/GitLab repository URLs) 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]): Files to upload.
raw_data (Optional[List[str]]): String inputs, one entry each:
- Raw text to ingest
- A local file or directory path on the server (requires ACCEPT_LOCAL_FILE_PATH)
- A web URL, fetched as a page (requires ALLOW_HTTP_REQUESTS)
- A GitHub/GitLab repository URL, shallow-cloned and indexed as a code graph At least one of data or raw_data is required. Uploads come first, then raw_data entries; labels and external_metadata pair with that combined order.
labels (Optional[str]): JSON array of per-item labels, e.g. [“finance”, “people”, ""], paired positionally with the data items (one entry per item; an empty entry skips that item). Stored on each item’s data record.
external_metadata (Optional[str]): JSON array of per-item metadata objects, e.g. [{“source”: “crm”}, null], paired positionally with the data items (one entry per item; null or {} skips that item). Merged into each item’s stored external_metadata.
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 used to organize and filter data points in the knowledge graph. Not an access-control mechanism.
run_in_background (Optional[bool]): Run add pipeline asynchronously (default: False).

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, or neither data nor raw_data provided
409 Conflict: A file in the request already exists in the dataset with different content. This endpoint never updates a document; send the new version to PATCH /api/v1/update?data_id=...&dataset_id=... so the document keeps its id. Re-adding identical content is a no-op, not an error.
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

add

Add (low level): ingest files, text or URLs into a dataset without building the graph

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'data=Cognee is a knowledge graph platform for AI applications.'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/add"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\nCognee is a knowledge graph platform for AI applications.\r\n-----011000010111000001101001--"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

{
  "status": "<string>",
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_name": "<string>",
  "data_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "payload": null,
  "data_ingestion_info": [
    "<unknown>"
  ]
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

data

file[]

raw_data

string[] | null

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.

Example:

[]

labels

string | null

Per-item labels, e.g. ["finance", "people", ""] — 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.

Example:

""

external_metadata

string | null

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.

Example:

""

datasetName

string | null

Name of the target dataset (created if it does not exist). Required unless datasetId is provided.

Example:

"default_dataset"

datasetId

Providing dataset ID is mandatory for sharing a dataset between users. Datasets provided by name will only be resolvable by dataset owner.

Example:

""

node_set

string[] | null

run_in_background

boolean | null

default:false

Response

Successful Response

status

string

required

pipeline_run_id

string<uuid>

required

dataset_id

string<uuid>

required

dataset_name

string

required

data_ids

string<uuid>[] | null

required

Ids of the Data rows this run processed, in result order.

For add() this is the id of every item that was stored (or already existed with the same content — dedup returns the existing row), so a caller can key later update() / delete_data() / find_data calls on cognee's own ids instead of re-deriving them. Items that errored are left out. None for run infos that carry no per-item results (PipelineRunStarted, progress ticks, the run infos nested in data_ingestion_info), which serialize without the key. Serialized with the model, so POST /api/v1/add responses carry it too.

payload

unknown

data_ingestion_info

any[] | null

⌘I

Add (low level): ingest files, text or URLs into a dataset without building the graph

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'data=Cognee is a knowledge graph platform for AI applications.'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/add"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"\r\n\r\nCognee is a knowledge graph platform for AI applications.\r\n-----011000010111000001101001--"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

{
  "status": "<string>",
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_name": "<string>",
  "data_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "payload": null,
  "data_ingestion_info": [
    "<unknown>"
  ]
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}