> ## 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. # 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 ## OpenAPI ````yaml /cognee_openapi_spec.json post /api/v1/add 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/add: post: tags: - add summary: >- Add (low level): ingest files, text or URLs into a dataset without building the graph description: >- 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 operationId: add_api_v1_add_post requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/Body_add_api_v1_add_post' example: data: Cognee is a knowledge graph platform for AI applications. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PipelineRunInfo' '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' '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: Body_add_api_v1_add_post: properties: data: items: type: string format: binary type: array title: Data raw_data: anyOf: - items: type: string example: '' type: array - type: 'null' title: Raw Data description: >- 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. examples: - [] labels: anyOf: - type: string - type: 'null' title: Labels description: >- 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. examples: - '' external_metadata: anyOf: - type: string - type: 'null' title: External Metadata description: >- 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. examples: - '' datasetName: anyOf: - type: string - type: 'null' title: Datasetname description: >- Name of the target dataset (created if it does not exist). Required unless datasetId is provided. examples: - default_dataset datasetId: anyOf: - type: string format: uuid - type: string const: '' - type: 'null' title: Datasetid description: >- Providing dataset ID is mandatory for sharing a dataset between users. Datasets provided by name will only be resolvable by dataset owner. examples: - '' node_set: anyOf: - items: type: string type: array - type: 'null' title: Node Set default: - '' run_in_background: anyOf: - type: boolean - type: 'null' title: Run In Background default: false type: object title: Body_add_api_v1_add_post 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 ````