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

# API Reference

> Complete API documentation for Cognee's knowledge graph platform

# Cognee API Reference

Welcome to the Cognee API documentation. This comprehensive reference covers all endpoints for building, managing, and querying your memory using Cognee's powerful platform.

## Getting Started

Before using the API, you need to choose how to run Cognee. You have two main options:

<CardGroup cols={2}>
  <Card title="Cognee Cloud" href="/how-to-guides/cognee-cloud/index" icon="cloud">
    **Managed Cloud Platform**

    Production-ready, fully managed service with automatic scaling and enterprise features.
  </Card>

  <Card title="Local Docker Setup" icon="docker">
    **Self-Hosted Development**

    Run Cognee locally using Docker for development, testing, and custom deployments.
  </Card>
</CardGroup>

## Setup Options

<Tabs>
  <Tab title="Cognee Cloud">
    **Managed Service - Recommended for Production**

    1. **Sign up** at [platform.cognee.ai](https://platform.cognee.ai/)
    2. **Create API Key** in your dashboard
    3. **Start using** the API immediately

    ```bash theme={null}
    # Base URL for Cognee Cloud
    BASE_URL="https://api.cognee.ai"

    # Authentication
    curl -H "X-Api-Key: YOUR-API-KEY" \
         -H "Content-Type: application/json" \
         $BASE_URL/health
    ```

    <Info>
      Cognee Cloud provides enterprise-grade infrastructure with automatic scaling, managed databases, and 24/7 monitoring.
    </Info>
  </Tab>

  <Tab title="Local Docker">
    **Self-Hosted - Perfect for Development**

    Quick start with Docker (single command):

    ```bash theme={null}
    # Create environment file
    echo 'LLM_API_KEY="your_openai_api_key"' > .env

    # Run Cognee container
    docker run --env-file ./.env -p 8000:8000 --rm -it cognee/cognee:main
    ```

    Or use Docker Compose from the [Cognee repository](https://github.com/topoteretes/cognee):

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

    # Set up environment
    cp .env.template .env
    # Edit .env with your API keys

    # Start with Docker Compose
    docker-compose up -d
    ```

    <Note>
      Local setup uses embedded databases by default (SQLite, LanceDB, NetworkX) for easy development.
    </Note>
  </Tab>
</Tabs>

## API Base URLs

<Warning>
  All Cognee API endpoints use the `/api/v1` prefix (e.g., `/api/v1/add`, `/api/v1/search`, `/api/v1/cognify`). The path `/api` **without** the version suffix is not a valid route and will return a 404 error. Always include `/api/v1` in your requests.
</Warning>

<AccordionGroup>
  <Accordion title="Production (Cognee Cloud)" defaultOpen>
    ```
    https://api.cognee.ai
    ```

    **Authentication**: X-Api-Key header
    **Rate Limits**: Based on your subscription plan
    **Availability**: 99.9% uptime SLA
  </Accordion>

  <Accordion title="Local Development">
    ```
    http://localhost:8000
    ```

    **Authentication**: Optional (can be disabled for local development)
    **Rate Limits**: None
    **Availability**: Depends on your local setup
  </Accordion>
</AccordionGroup>

## Authentication

<Tabs>
  <Tab title="Cognee Cloud">
    **API Key Authentication**

    All requests require an API key in the header:

    ```http theme={null}
    X-Api-Key: YOUR-API-KEY
    Content-Type: application/json
    ```

    Get your API key from the [Cognee Cloud dashboard](https://platform.cognee.ai/).
  </Tab>

  <Tab title="Local Docker">
    **Optional Authentication**

    Local development typically runs without authentication:

    ```http theme={null}
    Content-Type: application/json
    ```

    To enable authentication locally, set `REQUIRE_AUTHENTICATION=true` in your `.env` file, then call `POST /api/v1/auth/register` to create a user and `POST /api/v1/auth/login` to obtain a Bearer token. See the [Deploy REST API Server](/guides/deploy-rest-api-server#authentication) guide for full details.
  </Tab>
</Tabs>

## Core API Endpoints

The Cognee API provides endpoints for the complete knowledge graph lifecycle:

<CardGroup cols={2}>
  <Card title="Data Ingestion" icon="plus">
    **`POST /api/v1/add`**

    Add text, documents, or structured data to your knowledge base.
  </Card>

  <Card title="Knowledge Processing" icon="brain">
    **`POST /api/v1/cognify`**

    Transform raw data into structured knowledge graphs with entities and relationships.
  </Card>

  <Card title="Semantic Search" icon="search">
    **`POST /api/v1/search`**

    Query your knowledge graph using natural language or structured queries.
  </Card>

  <Card title="Data Management" icon="trash">
    **`DELETE /api/v1/datasets`**

    Remove specific data items or entire datasets from your knowledge base.
  </Card>
</CardGroup>

## API Features

<AccordionGroup>
  <Accordion title="Multiple Search Types">
    Choose from different search modes based on your needs:

    * **`GRAPH_COMPLETION`** (default): LLM-powered responses with graph context
    * **`RAG_COMPLETION`**: LLM answer from retrieved chunks
    * **`CHUNKS`**: Raw text segments matching your query
    * **`SUMMARIES`**: Pre-generated hierarchical summaries
    * **`TRIPLET_COMPLETION`**: Triple-based retrieval + LLM completion
    * **`CHUNKS_LEXICAL`**: Lexical (e.g. Jaccard) chunk search
    * **`CODING_RULES`**: Code-focused retrieval (coding rules / codebase)
    * **`TEMPORAL`**: Time-aware retrieval
    * **`GRAPH_COMPLETION_COT`**, **`GRAPH_COMPLETION_CONTEXT_EXTENSION`**, **`GRAPH_SUMMARY_COMPLETION`**: Advanced graph modes
    * **`CYPHER`**, **`NATURAL_LANGUAGE`**: Direct or inferred Cypher (disabled when `ALLOW_CYPHER_QUERY=false`)
    * **`FEELING_LUCKY`**: Auto-select search type

    Search also supports **`wide_search_top_k`**, **`triplet_distance_penalty`**, **`retriever_specific_config`**, and **`verbose`** for advanced control in the Python API. The HTTP `POST /api/v1/search` endpoint does not currently accept these advanced parameters. See [Search Basics](/guides/search-basics) and [Search](/core-concepts/main-operations/legacy-operations/search).
  </Accordion>

  <Accordion title="Flexible Data Formats">
    Support for various input formats locally and strings on Cognee Cloud:

    * **Text**: Raw text strings, documents, articles
    * **Structured**: JSON, CSV, XML data
    * **Code**: Source code files and repositories
    * **URLs**: Web pages and online content
  </Accordion>
</AccordionGroup>

## Data Deletion

Cognee provides granular control over data deletion through the `datasets` endpoints.

<CodeGroup>
  ```bash List Datasets theme={null}
  # List datasets you can access
  curl "http://localhost:8000/api/v1/datasets" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```bash List Dataset Data theme={null}
  # List data items in a dataset
  curl "http://localhost:8000/api/v1/datasets/{dataset_id}/data" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```bash Delete Data Item theme={null}
  # Delete a specific data item from a dataset
  curl -X DELETE "http://localhost:8000/api/v1/datasets/{dataset_id}/data/{data_id}" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```bash Delete Dataset theme={null}
  # Delete an entire dataset and all its contents
  curl -X DELETE "http://localhost:8000/api/v1/datasets/{dataset_id}" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```bash Delete All theme={null}
  # Delete all datasets you have delete permission on
  curl -X DELETE "http://localhost:8000/api/v1/datasets" \
    -H "Authorization: Bearer $TOKEN"
  ```
</CodeGroup>

<Note>
  Deletion requires the `delete` permission on the target dataset. See [Permissions](/core-concepts/multi-user-mode/permissions-system/overview) for details.\
  `DELETE /api/v1/delete` is deprecated. Use the `datasets` endpoints above instead.
</Note>

## Quick Example

Here's a complete example using the API:

<CodeGroup>
  ```python Python theme={null}
  import requests

  # Configuration
  BASE_URL = "http://localhost:8000"  # or https://api.cognee.ai for Cognee Cloud
  API_KEY = "your-api-key"  # only for Cognee Cloud

  headers = {
      "Content-Type": "application/json",
      "X-Api-Key": API_KEY  # only for Cognee Cloud
  }

  # 1. Add data
  add_response = requests.post(
      f"{BASE_URL}/api/v1/add",
      json={"data": "AI is transforming how we work and live."},
      headers=headers
  )

  # 2. Process into knowledge graph
  cognify_response = requests.post(
      f"{BASE_URL}/api/v1/cognify",
      json={"datasets": ["main_dataset"]},
      headers=headers
  )

  # 3. Search the knowledge graph
  search_response = requests.post(
      f"{BASE_URL}/api/v1/search",
      json={
          "query": "What is AI?",
          "search_type": "GRAPH_COMPLETION"
      },
      headers=headers
  )

  print(search_response.json())
  ```

  ```curl cURL theme={null}
  # 1. Add data
  curl -X POST "http://localhost:8000/api/v1/add" \
    -H "Content-Type: application/json" \
    -d '{"data": "AI is transforming how we work and live."}'

  # 2. Process into knowledge graph
  curl -X POST "http://localhost:8000/api/v1/cognify" \
    -H "Content-Type: application/json" \
    -d '{"datasets": ["main_dataset"]}'

  # 3. Search the knowledge graph
  curl -X POST "http://localhost:8000/api/v1/search" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What is AI?",
      "search_type": "GRAPH_COMPLETION"
    }'
  ```
</CodeGroup>

## Interactive API Explorer

<Card title="OpenAPI Specification" icon="play">
  **Try the API interactively**

  All endpoints on the left side of the page are automatically generated from our OpenAPI specification, providing interactive examples and real-time testing capabilities.
</Card>

<Tabs>
  <Tab title="Cognee Cloud">
    **Interactive Swagger Endpoint Docs**

    Our endpoints are also documented in Swagger with live testing capabilities. You can access the Swagger docs for Cognee Cloud at:

    ```bash theme={null}
    https://api.cognee.ai/docs
    ```
  </Tab>

  <Tab title="Local Docker">
    **Interactive Swagger Endpoint Docs**

    Our endpoints are also documented in Swagger with live testing capabilities. After you have started your local Cognee instance, you can access the Swagger docs at:

    ```bash theme={null}
    http://localhost:8000/docs
    ```
  </Tab>
</Tabs>

## Error Handling

All API endpoints return standard HTTP status codes. Use the troubleshooting notes below when a request does not behave as expected.

<AccordionGroup>
  <Accordion title="400 Bad Request">
    A `400 Bad Request` usually means the request shape is invalid.

    Check the following:

    * **Malformed JSON**: Make sure the request body is valid JSON and that quotes, commas, and braces are correct.
    * **Wrong content type**: JSON requests should include `Content-Type: application/json`.
    * **Missing required fields**: Compare your payload with the endpoint schema in the generated API reference below.
    * **Wrong parameter names**: Confirm field names such as `query`, `datasets`, or `search_type` exactly match the documented request body.
  </Accordion>

  <Accordion title="401 Unauthorized">
    A `401 Unauthorized` error means the server did not accept your authentication credentials.

    Check the following:

    * **Wrong auth method**: Cognee Cloud uses `X-Api-Key: YOUR-API-KEY`. Self-hosted instances use `Authorization: Bearer <token>` after `POST /api/v1/auth/login` when authentication is enabled.
    * **Missing or expired token**: If you are running locally with authentication enabled, register a user, log in again, and retry with a fresh Bearer token.
    * **Testing `GET /api/v1/users/me` without auth**: This endpoint is mainly useful when you are explicitly testing authentication. For unauthenticated local development, use other endpoints instead.
    * **Backend access control enabled**: If `ENABLE_BACKEND_ACCESS_CONTROL=true`, authentication is still required even when `REQUIRE_AUTHENTICATION=false`.

    For local auth setup, see [Deploy REST API Server](/guides/deploy-rest-api-server#authentication).
  </Accordion>

  <Accordion title="404 Not Found">
    A `404 Not Found` usually means the route or resource does not exist.

    Check the following:

    * **Wrong path prefix**: Use `/api/v1/...`, not `/api/...`. For example, `/api/users/me` returns a 404, while `/api/v1/users/me` is the correct path.
    * **Wrong HTTP method**: Confirm you are using the method documented for the endpoint, such as `POST` for `/api/v1/search`.
    * **Missing resource**: Dataset IDs, user IDs, or other resource identifiers may be validly formatted but not present in the current environment.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    A `429 Too Many Requests` response means you have hit a rate limit.

    Try the following:

    * **Retry with backoff**: Wait briefly before retrying, and increase the delay if the limit persists.
    * **Reduce burst traffic**: Spread out large batches of requests instead of sending them all at once.
    * **Handle retries in code**: Add retry logic so temporary throttling does not break your application flow.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    A `500 Internal Server Error` usually indicates a server-side failure.

    Check the following:

    * **Server logs**: Inspect the API server logs first to find the underlying exception.
    * **Provider configuration**: Verify your LLM, graph database, and vector database settings are valid.
    * **Problem isolation**: Retry with a smaller input or a simpler request to determine whether the issue is data-specific.
    * **Authentication and permissions side effects**: If the error appears only in multi-user mode, verify your auth and permissions configuration.
  </Accordion>
</AccordionGroup>

<Warning>
  Always implement proper error handling in your applications to gracefully handle API failures and rate limits.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Endpoints" icon="list">
    **API Documentation**

    Browse all available endpoints with interactive examples below.
  </Card>

  <Card title="Community Support" href="https://discord.gg/m63hxKsp4p" icon="discord">
    **Get Help**

    Join our Discord community for support and discussions.
  </Card>
</CardGroup>