Skip to main content
Deploy Cognee as a REST API server to expose its functionality via HTTP endpoints.

​
Setup

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

# Configure environment
cp .env.template .env
Edit .env with your preferred configuration. See Setup Configuration guides for all available options.

​
Deployment Methods

  • Docker
  • Python (Local)

​
Start Server

# Start API server
docker compose up --build cognee

# Check status
docker compose ps

​
Access API

​
Authentication

If REQUIRE_AUTHENTICATION=true in your .env file:
  1. Register: POST /api/v1/auth/register
  2. Login: POST /api/v1/auth/login
  3. Use token: Include Authorization: Bearer <token> header or use cookies

​
API Examples

Register a user:
curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "user1@example.com", "password": "strong_password"}'
Login and get token:
TOKEN="$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=user1@example.com&password=strong_password' | jq -r .access_token)"
Create a dataset:
curl -X POST http://localhost:8000/api/v1/datasets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "project_docs"}'
List datasets:
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/datasets
Add data (upload file):
curl -X POST http://localhost:8000/api/v1/add \
  -H "Authorization: Bearer $TOKEN" \
  -F "data=@/absolute/path/to/file.pdf" \
  -F "datasetName=project_docs"
Build knowledge graph:
curl -X POST http://localhost:8000/api/v1/cognify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"datasets": ["project_docs"]}'
Search data:
curl -X POST http://localhost:8000/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "What are the main topics?", "datasets": ["project_docs"], "top_k": 10}'
Create tenant:
curl -X POST "http://localhost:8000/api/v1/permissions/tenants?tenant_name=acme" \
  -H "Authorization: Bearer $TOKEN"
Add user to tenant:
curl -X POST "http://localhost:8000/api/v1/permissions/users/<user_id>/tenants?tenant_id=<tenant_id>" \
  -H "Authorization: Bearer $TOKEN"
Create role:
curl -X POST "http://localhost:8000/api/v1/permissions/roles?role_name=editor" \
  -H "Authorization: Bearer $TOKEN"
Assign user to role:
curl -X POST "http://localhost:8000/api/v1/permissions/users/<user_id>/roles?role_id=<role_id>" \
  -H "Authorization: Bearer $TOKEN"
Grant dataset permissions:
curl -X POST "http://localhost:8000/api/v1/permissions/datasets/<principal_id>?permission_name=read&dataset_ids=<ds_uuid_1>&dataset_ids=<ds_uuid_2>" \
  -H "Authorization: Bearer $TOKEN"

API Reference

Explore all API endpoints

Setup Configuration

Configure providers and databases

MCP Integration

Set up AI assistant integration