> ## 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.

# Deploy REST API Server

> Deploy Cognee as a REST API server using Docker or Python

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

## Setup

```bash theme={null}
# Clone repository
git clone https://github.com/topoteretes/cognee.git
cd cognee

# Configure environment
cp .env.template .env
```

<Info>
  Edit `.env` with your preferred configuration. See [Setup Configuration](/setup-configuration/overview) guides for all available options.
</Info>

## Deployment Methods

<Tabs>
  <Tab title="Docker">
    ### Start Server

    ```bash theme={null}
    # Start API server
    docker compose up --build cognee

    # Check status
    docker compose ps
    ```
  </Tab>

  <Tab title="Python (Local)">
    ### Setup

    ```bash theme={null}
    # Create virtual environment
    uv venv && source .venv/bin/activate

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

    ### Start Server

    ```bash theme={null}
    # Run API server
    uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000
    ```
  </Tab>
</Tabs>

## Access API

* **API:** [http://localhost:8000](http://localhost:8000)
* **Documentation:** [http://localhost:8000/docs](http://localhost:8000/docs)

## 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()`:

```python theme={null}
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()`:

```bash theme={null}
export COGNEE_SERVICE_URL="http://localhost:8000"
export COGNEE_API_KEY="<your-key>"  # required only when REQUIRE_AUTHENTICATION=true
```

```python theme={null}
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

<AccordionGroup>
  <Accordion title="Authentication">
    **Register a user:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    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)"
    ```
  </Accordion>

  <Accordion title="Dataset Management">
    **Create a dataset:**

    ```bash theme={null}
    curl -X POST http://localhost:8000/api/v1/datasets \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $TOKEN" \
      -d '{"name": "project_docs"}'
    ```

    **List datasets:**

    ```bash theme={null}
    curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/datasets
    ```
  </Accordion>

  <Accordion title="Data Operations">
    <Tabs>
      <Tab title="Cognee v1.0">
        **Remember data and build memory in one call:**

        ```bash theme={null}
        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:**

        ```bash theme={null}
        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:**

        ```bash theme={null}
        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:**

        ```bash theme={null}
        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}'
        ```
      </Tab>

      <Tab title="Legacy Operations">
        Use these lower-level endpoints when you want to keep ingestion, graph building, and retrieval as separate steps.

        **Add data (upload file):**

        ```bash theme={null}
        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:**

        ```bash theme={null}
        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:**

        ```bash theme={null}
        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}'
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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.                                                                        |

    <Tabs>
      <Tab title="Pipeline Runs">
        ```bash theme={null}
        curl -H "Authorization: Bearer $TOKEN" \
          "http://localhost:8000/api/v1/activity/pipeline-runs"
        ```
      </Tab>

      <Tab title="Trace Buffer">
        ```bash theme={null}
        curl -H "Authorization: Bearer $TOKEN" \
          "http://localhost:8000/api/v1/activity/spans"
        ```
      </Tab>

      <Tab title="Dataset Export">
        ```bash theme={null}
        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()`.
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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`.

    <Tabs>
      <Tab title="Infer Schema">
        ```bash theme={null}
        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."}'
        ```
      </Tab>

      <Tab title="Generate Prompt">
        ```bash theme={null}
        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": {...}, ...}}'
        ```
      </Tab>

      <Tab title="Use with Cognify">
        ```bash theme={null}
        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>"}'
        ```
      </Tab>
    </Tabs>

    Optional `parameters` keys for the LLM endpoints include `temperature`, `max_tokens`, `top_p`, and `seed`.
  </Accordion>

  <Accordion title="Multi-tenant Operations">
    **Create tenant:**

    ```bash theme={null}
    curl -X POST "http://localhost:8000/api/v1/permissions/tenants?tenant_name=acme" \
      -H "Authorization: Bearer $TOKEN"
    ```

    **Add user to tenant:**

    ```bash theme={null}
    curl -X POST "http://localhost:8000/api/v1/permissions/users/<user_id>/tenants?tenant_id=<tenant_id>" \
      -H "Authorization: Bearer $TOKEN"
    ```

    **Create role:**

    ```bash theme={null}
    curl -X POST "http://localhost:8000/api/v1/permissions/roles?role_name=editor" \
      -H "Authorization: Bearer $TOKEN"
    ```

    **Assign user to role:**

    ```bash theme={null}
    curl -X POST "http://localhost:8000/api/v1/permissions/users/<user_id>/roles?role_id=<role_id>" \
      -H "Authorization: Bearer $TOKEN"
    ```

    **Grant dataset permissions:**

    ```bash theme={null}
    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"
    ```
  </Accordion>
</AccordionGroup>

<Columns cols={3}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all API endpoints
  </Card>

  <Card title="Setup Configuration" icon="settings" href="/setup-configuration/overview">
    Configure providers and databases
  </Card>

  <Card title="MCP Integration" icon="plug" href="/cognee-mcp/mcp-overview">
    Set up AI assistant integration
  </Card>
</Columns>