Deploy REST API Server

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

API: http://localhost:8000
Documentation: http://localhost:8000/docs

Authentication

If REQUIRE_AUTHENTICATION=true in your .env file:

Register: POST /api/v1/auth/register
Login: POST /api/v1/auth/login
Use token: Include Authorization: Bearer <token> header or use cookies

API Examples

Authentication

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

Dataset Management

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

Data Operations

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}'

Multi-tenant Operations

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

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Setup

Deployment Methods

Start Server

Access API

Authentication

API Examples

API Reference

Setup Configuration

MCP Integration

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

​Setup

​Deployment Methods

​Start Server

​Access API

​Authentication

​API Examples

API Reference

Setup Configuration

MCP Integration

Setup

Deployment Methods

Start Server

Access API

Authentication

API Examples