Cognee API Reference

Welcome to the Cognee API documentation. This comprehensive reference covers all endpoints for building, managing, and querying your memory using Cognee’s powerful platform.

Getting Started

Before using the API, you need to choose how to run Cognee. You have two main options:

Cognee Cloud

Managed Cloud PlatformProduction-ready, fully managed service with automatic scaling and enterprise features.

Local Docker Setup

Self-Hosted DevelopmentRun Cognee locally using Docker for development, testing, and custom deployments.

Setup Options

Cognee Cloud
Local Docker

Managed Service - Recommended for Production

Sign up at platform.cognee.ai
Create API Key in your dashboard
Start using the API immediately

# Base URL for Cognee Cloud
BASE_URL="https://api.cognee.ai"

# Authentication
curl -H "X-Api-Key: YOUR-API-KEY" \
     -H "Content-Type: application/json" \
     $BASE_URL/api/health

Cognee Cloud provides enterprise-grade infrastructure with automatic scaling, managed databases, and 24/7 monitoring.

Self-Hosted - Perfect for DevelopmentQuick start with Docker (single command):

# Create environment file
echo 'LLM_API_KEY="your_openai_api_key"' > .env

# Run Cognee container
docker run --env-file ./.env -p 8000:8000 --rm -it cognee/cognee:main

Or use Docker Compose from the Cognee repository:

# Clone repository
git clone https://github.com/topoteretes/cognee.git
cd cognee

# Set up environment
cp .env.template .env
# Edit .env with your API keys

# Start with Docker Compose
docker-compose up -d

Local setup uses embedded databases by default (SQLite, LanceDB, NetworkX) for easy development.

API Base URLs

Production (Cognee Cloud)

https://api.cognee.ai

Authentication: X-Api-Key header Rate Limits: Based on your subscription plan Availability: 99.9% uptime SLA

Local Development

http://localhost:8000

Authentication: Optional (can be disabled for local development) Rate Limits: None Availability: Depends on your local setup

Authentication

Cognee Cloud
Local Docker

API Key AuthenticationAll requests require an API key in the header:

X-Api-Key: YOUR-API-KEY
Content-Type: application/json

Get your API key from the Cognee Cloud dashboard.

Optional AuthenticationLocal development typically runs without authentication:

Content-Type: application/json

To enable authentication locally, set REQUIRE_AUTH=true in your .env file.

Core API Endpoints

The Cognee API provides endpoints for the complete knowledge graph lifecycle:

Data Ingestion

POST /api/addAdd text, documents, or structured data to your knowledge base.

Knowledge Processing

POST /api/cognifyTransform raw data into structured knowledge graphs with entities and relationships.

Semantic Search

POST /api/searchQuery your knowledge graph using natural language or structured queries.

Data Management

DELETE /api/v1/datasetsRemove specific data items or entire datasets from your knowledge base.

API Features

Multiple Search Types

Choose from different search modes based on your needs:

GRAPH_COMPLETION (default): LLM-powered responses with graph context
RAG_COMPLETION: LLM answer from retrieved chunks
CHUNKS: Raw text segments matching your query
SUMMARIES: Pre-generated hierarchical summaries
TRIPLET_COMPLETION: Triple-based retrieval + LLM completion
CHUNKS_LEXICAL: Lexical (e.g. Jaccard) chunk search
CODING_RULES: Code-focused retrieval (coding rules / codebase)
TEMPORAL: Time-aware retrieval
GRAPH_COMPLETION_COT, GRAPH_COMPLETION_CONTEXT_EXTENSION, GRAPH_SUMMARY_COMPLETION: Advanced graph modes
CYPHER, NATURAL_LANGUAGE: Direct or inferred Cypher (disabled when ALLOW_CYPHER_QUERY=false)
FEELING_LUCKY: Auto-select search type

Search also supports wide_search_top_k, triplet_distance_penalty, retriever_specific_config, and verbose for advanced control in the Python API. The HTTP POST /api/v1/search endpoint does not currently accept these advanced parameters. See Search Basics and Search.

Flexible Data Formats

Support for various input formats locally and strings on Cognee Cloud:

Text: Raw text strings, documents, articles
Structured: JSON, CSV, XML data
Code: Source code files and repositories
URLs: Web pages and online content

Data Deletion

Cognee provides granular control over data deletion through the datasets endpoints.

# List datasets you can access
curl "http://localhost:8000/api/v1/datasets" \
  -H "Authorization: Bearer $TOKEN"

Deletion requires the delete permission on the target dataset. See Permissions for details.
DELETE /api/v1/delete is deprecated. Use the datasets endpoints above instead.

Quick Example

Here’s a complete example using the API:

import requests

# Configuration
BASE_URL = "http://localhost:8000"  # or https://api.cognee.ai for Cognee Cloud
API_KEY = "your-api-key"  # only for Cognee Cloud

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY  # only for Cognee Cloud
}

# 1. Add data
add_response = requests.post(
    f"{BASE_URL}/api/add",
    json={"data": "AI is transforming how we work and live."},
    headers=headers
)

# 2. Process into knowledge graph
cognify_response = requests.post(
    f"{BASE_URL}/api/cognify",
    json={"datasets": ["main_dataset"]},
    headers=headers
)

# 3. Search the knowledge graph
search_response = requests.post(
    f"{BASE_URL}/api/search",
    json={
        "query": "What is AI?",
        "search_type": "GRAPH_COMPLETION"
    },
    headers=headers
)

print(search_response.json())

Interactive API Explorer

OpenAPI Specification

Try the API interactivelyAll endpoints on the left side of the page are automatically generated from our OpenAPI specification, providing interactive examples and real-time testing capabilities.

Cognee Cloud
Local Docker

Interactive Swagger Endpoint DocsOur endpoints are also documented in Swagger with live testing capabilities. You can access the Swagger docs for Cognee Cloud at:

https://api.cognee.ai/docs

Interactive Swagger Endpoint DocsOur endpoints are also documented in Swagger with live testing capabilities. After you have started your local Cognee instance, you can access the Swagger docs at:

http://localhost:8000/docs

Error Handling

All API endpoints return standard HTTP status codes:

200: Success
400: Bad Request - Invalid parameters
401: Unauthorized - Invalid or missing API key
404: Not Found - Resource doesn’t exist
429: Too Many Requests - Rate limit exceeded
500: Internal Server Error - Server-side error

Always implement proper error handling in your applications to gracefully handle API failures and rate limits.

Next Steps

Explore Endpoints

API DocumentationBrowse all available endpoints with interactive examples below.

Community Support

Get HelpJoin our Discord community for support and discussions.

Getting Started

API Reference

auth

add

cognify

search

permissions

datasets

settings

visualize

delete

responses

code-pipeline

users

API Reference

Cognee API Reference

Getting Started

Cognee Cloud

Local Docker Setup

Setup Options

API Base URLs

Authentication

Core API Endpoints

Data Ingestion

Knowledge Processing

Semantic Search

Data Management

API Features

Data Deletion

Quick Example

Interactive API Explorer

OpenAPI Specification

Error Handling

Next Steps

Explore Endpoints

Community Support

Getting Started

API Reference

auth

add

cognify

search

permissions

datasets

settings

visualize

delete

responses

code-pipeline

users

​Cognee API Reference

​Getting Started

Cognee Cloud

Local Docker Setup

​Setup Options

​API Base URLs

​Authentication

​Core API Endpoints

Data Ingestion

Knowledge Processing

Semantic Search

Data Management

​API Features

​Data Deletion

​Quick Example

​Interactive API Explorer

OpenAPI Specification

​Error Handling

​Next Steps

Explore Endpoints

Community Support

Cognee API Reference

Getting Started

Setup Options

API Base URLs

Authentication

Core API Endpoints

API Features

Data Deletion

Quick Example

Interactive API Explorer

Error Handling

Next Steps