Skip to main content

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.

​
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

Managed Service - Recommended for Production
  1. Sign up at platform.cognee.ai
  2. Create API Key in your dashboard
  3. 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/health
Cognee Cloud provides enterprise-grade infrastructure with automatic scaling, managed databases, and 24/7 monitoring.

​
API Base URLs

All Cognee API endpoints use the /api/v1 prefix (e.g., /api/v1/add, /api/v1/search, /api/v1/cognify). The path /api without the version suffix is not a valid route and will return a 404 error. Always include /api/v1 in your requests.

Production (Cognee Cloud)

https://api.cognee.ai
Authentication: X-Api-Key header Rate Limits: Based on your subscription plan Availability: 99.9% uptime SLA
http://localhost:8000
Authentication: Optional (can be disabled for local development) Rate Limits: None Availability: Depends on your local setup

​
Authentication

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.

​
Core API Endpoints

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

Data Ingestion

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

Knowledge Processing

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

Semantic Search

POST /api/v1/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

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.
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/v1/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/v1/cognify",
    json={"datasets": ["main_dataset"]},
    headers=headers
)

# 3. Search the knowledge graph
search_response = requests.post(
    f"{BASE_URL}/api/v1/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.
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

​
Error Handling

All API endpoints return standard HTTP status codes. Use the troubleshooting notes below when a request does not behave as expected.
A 400 Bad Request usually means the request shape is invalid.Check the following:
  • Malformed JSON: Make sure the request body is valid JSON and that quotes, commas, and braces are correct.
  • Wrong content type: JSON requests should include Content-Type: application/json.
  • Missing required fields: Compare your payload with the endpoint schema in the generated API reference below.
  • Wrong parameter names: Confirm field names such as query, datasets, or search_type exactly match the documented request body.
A 401 Unauthorized error means the server did not accept your authentication credentials.Check the following:
  • Wrong auth method: Cognee Cloud uses X-Api-Key: YOUR-API-KEY. Self-hosted instances use Authorization: Bearer <token> after POST /api/v1/auth/login when authentication is enabled.
  • Missing or expired token: If you are running locally with authentication enabled, register a user, log in again, and retry with a fresh Bearer token.
  • Testing GET /api/v1/users/me without auth: This endpoint is mainly useful when you are explicitly testing authentication. For unauthenticated local development, use other endpoints instead.
  • Backend access control enabled: If ENABLE_BACKEND_ACCESS_CONTROL=true, authentication is still required even when REQUIRE_AUTHENTICATION=false.
For local auth setup, see Deploy REST API Server.
A 404 Not Found usually means the route or resource does not exist.Check the following:
  • Wrong path prefix: Use /api/v1/..., not /api/.... For example, /api/users/me returns a 404, while /api/v1/users/me is the correct path.
  • Wrong HTTP method: Confirm you are using the method documented for the endpoint, such as POST for /api/v1/search.
  • Missing resource: Dataset IDs, user IDs, or other resource identifiers may be validly formatted but not present in the current environment.
A 429 Too Many Requests response means you have hit a rate limit.Try the following:
  • Retry with backoff: Wait briefly before retrying, and increase the delay if the limit persists.
  • Reduce burst traffic: Spread out large batches of requests instead of sending them all at once.
  • Handle retries in code: Add retry logic so temporary throttling does not break your application flow.
A 500 Internal Server Error usually indicates a server-side failure.Check the following:
  • Server logs: Inspect the API server logs first to find the underlying exception.
  • Provider configuration: Verify your LLM, graph database, and vector database settings are valid.
  • Problem isolation: Retry with a smaller input or a simpler request to determine whether the issue is data-specific.
  • Authentication and permissions side effects: If the error appears only in multi-user mode, verify your auth and permissions configuration.
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.