cognify

Cognify (low level): build the knowledge graph from already-added data

Transform 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

Document classification and permission validation
Text chunking and semantic segmentation
Entity extraction using LLM-powered analysis
Relationship detection and graph construction
Vector embeddings generation for semantic search
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).
graph_model (Optional[dict]): JSON schema describing a custom graph model for entity extraction. When omitted or {}, the default KnowledgeGraph model is used.
custom_prompt (Optional[str]): Custom prompt for entity extraction and graph generation. If provided, this prompt will be used instead of the default prompts for knowledge graph extraction.
chunk_size (Optional[int]): Maximum tokens per chunk. If omitted, Cognee chooses a size from the configured LLM and embedding limits.
ontology_key (Optional[List[str]]): Reference to one or more previously uploaded ontology files to use for knowledge graph construction.
chunks_per_batch (Optional[int]): Number of chunks to process per task batch in Cognify. Uses the pipeline default when omitted.
data_per_batch (Optional[int]): Maximum number of data items to process concurrently within a dataset. Defaults to 20.

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
409 Conflict: When a referenced ontology_key does not exist
500 Internal Server Error: When the pipeline run errors (e.g. missing LLM API key, database connection failure, or a dataset that does not exist)

Example Request

{
    "datasets": ["research_papers", "documentation"],
    "run_in_background": false,
    "custom_prompt": "Extract entities focusing on technical concepts and their relationships. Identify key technologies, methodologies, and their interconnections.",
    "ontology_key": ["medical_ontology_v1"]
}

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.

POST

api

cognify

Cognify (low level): build the knowledge graph from already-added data

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/cognify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "datasets": [
    "main_dataset"
  ]
}
'

import requests

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

payload = { "datasets": ["main_dataset"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{}

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

{
  "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

application/json

datasets

string[] | null

Dataset names to process; resolved against datasets owned by the authenticated user.

Example:

["default_dataset"]

datasetIds

string<uuid>[] | null

Dataset UUIDs to process (required for datasets shared with you). Takes precedence over the datasets name list when both are provided.

Example:

[]

runInBackground

boolean | null

default:false

If true, the request returns immediately with a pipeline_run_id while the graph builds server-side — track completion via GET /v1/datasets/status or the /v1/cognify/subscribe WebSocket. If false, the request blocks until the knowledge graph is fully built, which can take minutes for large datasets.

graphModel

Graphmodel · object | null

JSON schema describing a custom graph model for entity extraction, including a top-level 'title' key. When omitted or {}, the default KnowledgeGraph model is used — a restrictive schema here can produce an empty graph.

Example:

{}

customPrompt

string | null

default:""

Replaces the default entity-extraction prompt to steer which entities and relationships get extracted (e.g. 'Extract entities focusing on technical concepts and their relationships.'). Leave empty for the default prompt.

Example:

""

chunkSize

integer | null

Maximum tokens per chunk (e.g. 4096). Leave null for automatic model-based sizing. Larger chunks give more context per LLM extraction pass; smaller chunks give finer-grained extraction at higher LLM cost.

Example:

null

ontologyKey

string[] | null

Keys of previously uploaded ontologies (see /v1/ontologies) to ground entity extraction. Leave empty to process without an ontology.

Example:

[]

chunksPerBatch

integer | null

Number of chunks to process per task batch (e.g. 36). Controls processing parallelism/throughput; leave null for the pipeline default. Higher the value higher the parallelism/throughput

Example:

null

dataPerBatch

integer | null

default:20

Maximum number of data items to process concurrently within a dataset.

Example:

20

Response

Successful Response

{key}

PipelineRunInfo · object

Show child attributes

⌘I

Cognify (low level): build the knowledge graph from already-added data

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/cognify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "datasets": [
    "main_dataset"
  ]
}
'

import requests

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

payload = { "datasets": ["main_dataset"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{}

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

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

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

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

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