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 for graph organization and access control. Used for grouping related data points in the knowledge graph.
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.' \
  --form data.items='@example-file'

import requests

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

files = { "data.items": ("example-file", open("example-file", "rb")) }
payload = { "data": "Cognee is a knowledge graph platform for AI applications." }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, 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>",
  "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

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.' \
  --form data.items='@example-file'

import requests

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

files = { "data.items": ("example-file", open("example-file", "rb")) }
payload = { "data": "Cognee is a knowledge graph platform for AI applications." }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, 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>",
  "payload": null,
  "data_ingestion_info": [
    "<unknown>"
  ]
}

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

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

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

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