OpenAPI Specification
openapi: 3.0.3
info:
title: Cognee REST agents datasets API
description: 'The Cognee REST API provides endpoints for the complete AI memory lifecycle, including data ingestion, knowledge graph construction, and semantic retrieval. Core endpoints cover adding raw text or documents, triggering the cognify pipeline that extracts entities and relationships via LLM, executing multi-mode search queries, managing datasets, and creating agent identities. The API uses X-Api-Key header authentication for cloud deployments and Bearer token auth for self-hosted instances.
'
version: 1.0.0
contact:
name: Cognee Support
url: https://docs.cognee.ai/api-reference/introduction
license:
name: Apache 2.0
url: https://github.com/topoteretes/cognee/blob/main/LICENSE
servers:
- url: https://api.cognee.ai
description: Cognee Cloud (managed)
- url: http://localhost:8000
description: Self-hosted (Docker / local)
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: datasets
description: Dataset management and introspection
paths:
/api/v1/datasets:
get:
operationId: getDatasets
summary: List all accessible datasets
description: 'Retrieves all datasets the authenticated user has read permission for, including metadata such as ID, name, creation time, and owner.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
responses:
'200':
description: List of datasets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
'418':
description: Error retrieving datasets
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createDataset
summary: Create a new dataset
description: 'Creates a new dataset with the specified name. If a dataset with the same name already exists for the user, returns the existing dataset. The user is automatically granted all permissions on the created dataset.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: Name for the new dataset
example: my_documents
responses:
'200':
description: Created or existing dataset
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'418':
description: Error creating dataset
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: deleteAllDatasets
summary: Delete all user datasets
description: 'Permanently deletes all datasets and associated data owned by the authenticated user. If no datasets exist, this operation is a no-op.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
responses:
'200':
description: All datasets deleted
/api/v1/datasets/status:
get:
operationId: getDatasetStatus
summary: Get dataset processing status
description: 'Retrieves the current processing status for one or more datasets. If one pipeline is specified, returns a flat {dataset_id: status} map. If multiple pipelines are specified, returns a nested {dataset_id: {pipeline: status}} map.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: dataset
in: query
style: form
explode: true
schema:
type: array
items:
type: string
format: uuid
description: List of dataset UUIDs to check
- name: pipeline
in: query
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- add_pipeline
- cognify_pipeline
description: Pipeline names to check (default cognify_pipeline)
responses:
'200':
description: Status map for requested datasets
content:
application/json:
schema:
type: object
additionalProperties:
type: string
enum:
- pending
- running
- completed
- failed
'500':
description: Error retrieving status
/api/v1/datasets/{dataset_id}:
delete:
operationId: deleteDataset
summary: Delete a dataset by ID
description: 'Permanently deletes a dataset and all its associated data. Requires delete permissions on the dataset.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Dataset deleted
'404':
description: Dataset not found or access denied
'500':
description: Error during deletion
/api/v1/datasets/{dataset_id}/data:
get:
operationId: getDatasetData
summary: List all data items in a dataset
description: 'Returns metadata for all data items (documents, files, etc.) in the specified dataset. Each item includes name, type, MIME type, and storage location.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: List of data items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataItem'
'404':
description: Dataset not found
'500':
description: Internal error
/api/v1/datasets/{dataset_id}/data/{data_id}:
delete:
operationId: deleteDataItem
summary: Delete a specific data item from a dataset
description: 'Removes a specific data item from a dataset while keeping the dataset intact. Requires delete permissions on the dataset.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: data_id
in: path
required: true
schema:
type: string
format: uuid
description: Unique identifier of the data item
responses:
'200':
description: Data item deleted
'404':
description: Dataset or data item not found
'500':
description: Error during deletion
/api/v1/datasets/{dataset_id}/data/{data_id}/raw:
get:
operationId: downloadRawData
summary: Download the raw data file for a data item
description: 'Returns the original unprocessed data file for a specific data item. Supports local filesystem and S3 storage backends.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: data_id
in: path
required: true
schema:
type: string
format: uuid
description: Unique identifier of the data item
responses:
'200':
description: Raw file download
content:
application/octet-stream:
schema:
type: string
format: binary
'404':
description: Dataset or data item not found
'501':
description: Storage scheme not supported
/api/v1/datasets/{dataset_id}/graph:
get:
operationId: getDatasetGraph
summary: Get knowledge graph for a dataset
description: 'Retrieves the knowledge graph visualization data for a specific dataset, including all nodes and edges representing entity relationships.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Knowledge graph nodes and edges
content:
application/json:
schema:
$ref: '#/components/schemas/Graph'
'404':
description: Dataset not found
'500':
description: Error retrieving graph
/api/v1/datasets/{dataset_id}/schema:
get:
operationId: getDatasetSchema
summary: Get graph schema for a dataset
description: Returns the stored graph schema and custom prompt for a dataset.
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Dataset schema and custom prompt
content:
application/json:
schema:
type: object
properties:
graph_schema:
type: object
nullable: true
custom_prompt:
type: string
nullable: true
'404':
description: Dataset not found
put:
operationId: updateDatasetSchema
summary: Update graph schema for a dataset
description: 'Store or update the graph schema and custom prompt for a dataset. Requires write permissions on the dataset.
'
tags:
- datasets
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
graph_schema:
type: object
nullable: true
description: JSON schema for the knowledge graph structure
custom_prompt:
type: string
nullable: true
description: Custom extraction prompt for this dataset
responses:
'200':
description: Schema updated
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
'404':
description: Dataset not found
components:
schemas:
GraphNode:
type: object
properties:
id:
type: string
format: uuid
label:
type: string
type:
type: string
properties:
type: object
required:
- id
- label
- type
- properties
GraphEdge:
type: object
properties:
source:
type: string
format: uuid
target:
type: string
format: uuid
label:
type: string
required:
- source
- target
- label
Dataset:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
nullable: true
owner_id:
type: string
format: uuid
required:
- id
- name
- created_at
- owner_id
ErrorResponse:
type: object
properties:
error:
type: string
description: Short error message
detail:
type: string
nullable: true
description: Detailed error description
required:
- error
DataItem:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
nullable: true
extension:
type: string
mime_type:
type: string
raw_data_location:
type: string
dataset_id:
type: string
format: uuid
required:
- id
- name
- created_at
- extension
- mime_type
- raw_data_location
- dataset_id
Graph:
type: object
properties:
nodes:
type: array
items:
$ref: '#/components/schemas/GraphNode'
edges:
type: array
items:
$ref: '#/components/schemas/GraphEdge'
required:
- nodes
- edges
parameters:
DatasetId:
name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Unique identifier of the dataset
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token authentication for self-hosted instances
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
description: API key authentication for Cognee Cloud deployments
externalDocs:
description: Cognee API Reference
url: https://docs.cognee.ai/api-reference/introduction