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

​
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

​
Python SDK Client

After deploying the server, connect the Python SDK to your running instance using cognee.serve(): 
import cognee
import asyncio

async def main():
    client = await cognee.serve(url="http://localhost:8000")
    # Pass api_key="..." only when REQUIRE_AUTHENTICATION=true

    # Ingest data and build the knowledge graph in one step
    await client.remember("Cognee turns documents into AI memory.", dataset_name="docs")

    # Query the knowledge graph
    results = await client.recall("What does Cognee do?")
    for result in results:
        print(result)

    await cognee.disconnect()

asyncio.run(main())
You can also configure the connection via environment variables instead of passing arguments to serve(): 
export COGNEE_SERVICE_URL="http://localhost:8000"
export COGNEE_API_KEY="<your-key>"  # required only when REQUIRE_AUTHENTICATION=true

client = await cognee.serve()  # reads COGNEE_SERVICE_URL and COGNEE_API_KEY
The CloudClient returned by serve() exposes four methods that map to the server’s V2 endpoints: remember() (ingest + cognify), recall() (search), improve() (enrich graph), and forget() (delete). Call await cognee.disconnect() to revert to local mode.

​
HTTP 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