Deploy REST API Server - Cognee Documentation

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

Setup

# Create virtual environment
uv venv && source .venv/bin/activate

# Install with all extras
uv sync --all-extras

Start Server

# Run API server
uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000

Alternatively, launch the server through the module entry point, which accepts a --agent-mode flag:

# Standard mode (defaults to port 8000)
python cognee/api/client.py

# Agent mode (defaults to port 8011)
python cognee/api/client.py --agent-mode

Passing --agent-mode sets COGNEE_AGENT_MODE=true for the process and overrides the environment variable if it is also set. Agent mode is intended for ephemeral deployments where an orchestrator spins up Cognee for one or more agents; the server tracks agents that call POST /api/v1/agents/register and shuts itself down once the active count drops back to zero (driven by POST /api/v1/agents/unregister). The auto-shutdown watchdog only starts after the first connection registers, so a fresh agent-mode server stays up while it waits. Host and port can still be overridden with HTTP_API_HOST and HTTP_API_PORT.

Access API

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

Agent Mode

Cognee can run in agent mode, which tracks active agent connections and shuts the server down once they all disconnect. This is intended for ephemeral deployments where an external orchestrator launches a Cognee server for one or more agents and tears it down when they finish. Enable agent mode in either of two ways:

# CLI flag (when running the API server directly)
python -m cognee.api.client --agent-mode

# Environment variable
COGNEE_AGENT_MODE=true uvicorn cognee.api.client:app --host 0.0.0.0

When agent mode is enabled:

The default port becomes 8011 (instead of 8000). The CLI flag overrides the COGNEE_AGENT_MODE env var. HTTP_API_PORT still wins if you set it explicitly.
A background watchdog starts after the first POST /api/v1/agents/register call and checks the active connection count every 60 seconds. When the count drops to zero, the watchdog sends SIGTERM to the server process.
The server stays alive indefinitely while waiting for the first registration — the watchdog does not arm until then.

Agents call POST /api/v1/agents/register on connect and POST /api/v1/agents/unregister on disconnect; see the Agent Management accordion below for the full surface.

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

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

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

Cognee v1.0
Legacy Operations

Remember data and build memory in one call:

curl -X POST http://localhost:8000/api/v1/remember \
  -H "Authorization: Bearer $TOKEN" \
  -F "data=@/absolute/path/to/file.pdf" \
  -F "datasetName=project_docs" \
  -F "chunk_size=1024" \
  -F "chunks_per_batch=20" \
  -F "run_in_background=false"

Recall from a dataset with explicit retrieval settings:

curl -X POST http://localhost:8000/api/v1/recall \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "What are the main topics?", "datasets": ["project_docs"], "search_type": "GRAPH_COMPLETION", "top_k": 10}'

Improve an existing dataset in the background:

curl -X POST http://localhost:8000/api/v1/improve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"dataset_name": "project_docs", "run_in_background": true}'

Forget only derived memory and keep the uploaded files:

curl -X POST http://localhost:8000/api/v1/forget \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"dataset": "project_docs", "memory_only": true}'

Use these lower-level endpoints when you want to keep ingestion, graph building, and retrieval as separate steps.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 the knowledge graph with a custom chunk size:

curl -X POST http://localhost:8000/api/v1/cognify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"datasets": ["project_docs"], "chunk_size": 1024}'

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

Activity and Observability

The /api/v1/activity router exposes endpoints for pipeline run history, trace data, tenant or agent monitoring, and dataset export. All endpoints require authentication.

Endpoint	Description
`GET /api/v1/activity/pipeline-runs`	Last 50 pipeline runs with dataset name and owner. Accepts optional `?dataset_id=<uuid>` to filter by dataset.
`GET /api/v1/activity/spans`	In-memory OTEL span buffer (last 50 traces). Requires `COGNEE_TRACING_ENABLED=true`. Returns an empty list when tracing is disabled.
`GET /api/v1/activity/users`	All active users in the current tenant.
`GET /api/v1/activity/agents`	Registered agents with `status` (`LIVE` / `INACTIVE`), API key count, and recent activity flag.
`GET /api/v1/activity/export/{dataset_id}`	Downloads the dataset’s knowledge graph as a Markdown export.

Pipeline Runs
Trace Buffer
Dataset Export

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/activity/pipeline-runs"

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/activity/spans"

curl -L -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/activity/export/<dataset_id>"

  The `/api/v1/activity/spans` response mirrors the same in-memory trace buffer used by the Python OpenTelemetry helpers such as `get_all_traces()`.

LLM Utility Endpoints

When running Cognee as a server, two /api/v1/llm endpoints can help you bootstrap a custom extraction prompt from sample text:

POST /api/v1/llm/infer-schema — analyze sample text and return a graph schema
POST /api/v1/llm/custom-prompt — generate a custom extraction prompt from that schema

Typical flow: infer a schema from sample text, generate a prompt, then pass that prompt to POST /api/v1/cognify.

Infer Schema
Generate Prompt
Use with Cognify

curl -X POST "http://localhost:8000/api/v1/llm/infer-schema" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Alice moved to Paris. Bob founded Acme Corp in New York."}'

curl -X POST "http://localhost:8000/api/v1/llm/custom-prompt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"graphModel": {"title": "PersonCityNetwork", "$defs": {...}, ...}}'

curl -X POST "http://localhost:8000/api/v1/cognify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datasets": ["my_dataset"], "custom_prompt": "<prompt from step 2>"}'

Optional parameters keys for the LLM endpoints include temperature, max_tokens, top_p, and seed.

Agent Management

The /api/v1/agents router exposes two groups of endpoints: agent management (create / list / get / delete an agent identity) and agent connections (register, unregister, and inspect live sessions). All endpoints require authentication. Agent identities are persisted as child users of the calling user, keyed by UUID (agentId in API responses), and authenticate to Cognee using the API key returned on creation — agents do not have passwords.

Endpoint	Description
`POST /api/v1/agents/create?name=<name>`	Create an agent identity. Returns `agentId` (UUID), a synthesized `agentEmail`, and the one-time `agentApiKey`. Store the key — it is not retrievable later. Returns `409` if an agent with that name already exists for the caller.
`GET /api/v1/agents/list`	List agents created by the authenticated user. Each item includes `agentId`, `agentEmail`, and `apiKeyLabel`.
`GET /api/v1/agents/{agent_id}`	Fetch a single agent. `404` if not found, `403` if the caller does not own it.
`DELETE /api/v1/agents/{agent_id}`	Delete an agent. `404` / `403` as above.
`POST /api/v1/agents/register`	Register an agent connection (session). Body uses `RegisterAgentRequest` (see below). Returns the created `AgentConnection`. `201 Created`.
`POST /api/v1/agents/unregister`	Deactivate a connection. Body: `{ "agent_session_name": "<name>" }`. Returns `{ "activeAgents": <count> }`.
`GET /api/v1/agents/connections`	List agent connections visible to the caller. Filters: `agent_id`, `range` (`24h`/`7d`/`30d`/`all`, default `30d`), `status` (`active`/`inactive`/`unknown`), `include_sources`, `active_only`, `limit` (1–500, default 50), `offset`.
`GET /api/v1/agents/connections/me`	Connection detail for the authenticated user’s own agent connection. Optional `agent_session_name` query filter. `404` if no matching connection.
`GET /api/v1/agents/connections/{agent_id}`	Connection detail for a specific agent. Optional `agent_session_name` query filter.

RegisterAgentRequest body fields: agent_session_name (required — combined with the caller’s user ID to form the connection ID), type (sdk/api/mcp/claude_code/workflow/unknown, default api), memory_mode (session/cognee/hybrid/none/unknown), session_id, dataset_ids, dataset_names, source, origin_function, metadata.

Create an Agent
Register a Connection
Unregister

curl -X POST "http://localhost:8000/api/v1/agents/create?name=my-agent" \
  -H "Authorization: Bearer $TOKEN"
# {
#   "agentId": "f3b0...-...",
#   "agentEmail": "my-agent@cognee.agent",
#   "agentApiKey": "ck_..."
# }

curl -X POST "http://localhost:8000/api/v1/agents/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_session_name": "my-agent-session",
    "type": "sdk",
    "memory_mode": "cognee",
    "dataset_names": ["project_docs"]
  }'

curl -X POST "http://localhost:8000/api/v1/agents/unregister" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_session_name": "my-agent-session"}'
# {"activeAgents": 0}

When the server runs in agent mode, register and unregister drive the auto-shutdown watchdog. The same agent_session_name registered twice by the same user counts as a single connection — registration is idempotent on the connection ID.

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

​Setup

​Deployment Methods

​Start Server

​Setup

​Start Server

​Access API

​Agent Mode

​Authentication

​Python SDK Client

​HTTP API Examples

API Reference

Setup Configuration

MCP Integration

Setup

Deployment Methods

Start Server

Setup

Start Server

Access API

Agent Mode

Authentication

Python SDK Client

HTTP API Examples