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

# Cognee Cloud HTTP API

> The endpoint reference for your Cognee Cloud tenant.

Your tenant serves the same HTTP API as a self-hosted Cognee server — the same paths under `/api/v1/`, the same request and response shapes. Every endpoint is listed in the sidebar, generated from the OpenAPI specification and backed by an interactive playground.

This page covers what is specific to calling that API against Cognee Cloud: where to point it, how to authenticate, and which failures you should expect to see. For the self-hosted setup — running the server under Docker, enabling local authentication, and the environment variables behind these behaviors — see the [API Reference](/api-reference/introduction).

## Base URL

Your tenant has its own host:

```
https://your-tenant.aws.cognee.ai
```

Copy the exact value from the **Connection Details** card on the [API Keys](/cognee-cloud/ui/api-keys) page — `your-tenant` is a placeholder, not a live host.

<Warning>
  Every endpoint uses the `/api/v1` prefix (`/api/v1/add`, `/api/v1/search`, `/api/v1/cognify`). The path `/api` **without** the version suffix is not a valid route and returns `404`.
</Warning>

## Authentication

All requests carry your API key in a header:

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

Create and copy keys on the [API Keys](/cognee-cloud/ui/api-keys) page, which also shows both header values ready to paste. Bearer tokens and `POST /api/v1/auth/login` belong to self-hosted instances with authentication enabled — on Cloud, the API key is the credential.

## Quick example

<CodeGroup>
  ```bash cURL theme={null}
  BASE_URL="https://your-tenant.aws.cognee.ai"

  # 1. Add data
  curl -X POST "$BASE_URL/api/v1/add" \
    -H "X-Api-Key: $COGNEE_API_KEY" \
    -F "datasetName=my_dataset" \
    -F "raw_data=AI is transforming how we work and live."

  # 2. Process it into a knowledge graph
  curl -X POST "$BASE_URL/api/v1/cognify" \
    -H "X-Api-Key: $COGNEE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"datasets": ["my_dataset"]}'

  # 3. Search the graph
  curl -X POST "$BASE_URL/api/v1/search" \
    -H "X-Api-Key: $COGNEE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "What is AI?", "search_type": "GRAPH_COMPLETION"}'
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE_URL = "https://your-tenant.aws.cognee.ai"
  headers = {"X-Api-Key": os.environ["COGNEE_API_KEY"]}

  # 1. Add data
  requests.post(
      f"{BASE_URL}/api/v1/add",
      headers=headers,
      data={"datasetName": "my_dataset"},
      files=[("raw_data", (None, "AI is transforming how we work and live."))],
  )

  # 2. Process it into a knowledge graph
  requests.post(
      f"{BASE_URL}/api/v1/cognify",
      headers={**headers, "Content-Type": "application/json"},
      json={"datasets": ["my_dataset"]},
  )

  # 3. Search the graph
  response = requests.post(
      f"{BASE_URL}/api/v1/search",
      headers={**headers, "Content-Type": "application/json"},
      json={"query": "What is AI?", "search_type": "GRAPH_COMPLETION"},
  )
  print(response.json())
  ```
</CodeGroup>

<Note>
  `POST /api/v1/add` and `POST /api/v1/remember` take multipart form data. Send string inputs through the repeated `raw_data` form field, and files through `data`. See [Data Ingestion](/cognee-cloud/functionality/data-ingestion).
</Note>

## Core endpoints

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

    Add text, documents, or structured data to a dataset.
  </Card>

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

    Turn ingested data into a knowledge graph of entities and relationships.
  </Card>

  <Card title="Ingest and Process" icon="wand-magic-sparkles">
    **`POST /api/v1/remember`**

    Do both in one call, with control over chunking, ontologies, and the graph model.
  </Card>

  <Card title="Search" icon="magnifying-glass">
    **`POST /api/v1/search`**

    Query the graph in natural language. Pick a `search_type` to trade depth for latency — see [Search and Recall](/cognee-cloud/functionality/search-and-recall).
  </Card>

  <Card title="Dataset Management" icon="database">
    **`/api/v1/datasets/*`**

    List datasets, inspect their contents, and delete a data item or a whole dataset. See [Dataset Management](/cognee-cloud/functionality/dataset-management).
  </Card>

  <Card title="Recall" icon="brain-circuit">
    **`POST /api/v1/recall`**

    Retrieve memory for an agent turn, including session context. See [Search and Recall](/cognee-cloud/functionality/search-and-recall).
  </Card>
</CardGroup>

## Trying a request from these docs

Each endpoint page carries a playground. Open **Try it**, then:

1. Under **Server**, fill the `tenant` field. It is prefilled with the placeholder `your-tenant`, which is not a live host — replace it with your own.
2. Add your `X-Api-Key`.

Swagger UI is available too: the shared docs at [`api.aws.cognee.ai/docs`](https://api.aws.cognee.ai/docs), and your tenant's own at `https://your-tenant.aws.cognee.ai/docs`.

## Error handling

When a request fails inside Cognee, the response carries that error's HTTP status and a `detail` field holding the message followed by the error class name:

```json theme={null}
{
  "detail": "<message> [<ErrorName>]"
}
```

When Cognee knows what would make the error go away, the body carries an extra `remediation` key next to it — a short prescriptive hint, not a restatement of `detail`. It is optional and additive: the key is simply absent when no fix is known, so read `detail` and treat `remediation` as a hint to show a human or an agent rather than something to branch on.

A few routes still return a generic body for unexpected errors: `500` with `{"error": "Internal server error", "detail": "..."}` for search, and `409` with `{"error": "..."}` for recall, remember, and improve. These never carry `remediation`.

<AccordionGroup>
  <Accordion title="400 Bad Request">
    The request shape is invalid. Check that the body is valid JSON with the documented field names, that JSON requests set `Content-Type: application/json`, and that required fields are present — `POST /api/v1/search` and `POST /api/v1/recall` both require a `query` string, and a body omitting it is rejected rather than answered against a default question.

    A custom `graph_model` schema may only reference its own document. A `$ref` that does not start with `#` — a URL, a `file://` URI, or a filesystem path — is rejected instead of fetched, so the server never makes a network request on your behalf. Inline the referenced schema under `$defs` and point the `$ref` at it, for example `#/$defs/Node`.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your credentials were not accepted. Confirm you are sending `X-Api-Key: YOUR-API-KEY` — a `Authorization: Bearer` token is the self-hosted auth method and will not work here — and that the key is still active on the [API Keys](/cognee-cloud/ui/api-keys) page.
  </Accordion>

  <Accordion title="402 Payment Required">
    The token budget for the request is exhausted, on either the LLM or the embedding path:

    ```json theme={null}
    {
      "detail": "LLM provider requires payment or token budget is exhausted. [LLMPaymentRequiredError]"
    }
    ```

    This status is **terminal**. The request is excluded from automatic retries and re-submitting it fails the same way until credits are restored — add credits on the Billing page (workspace owners only — see [Account and Billing](/cognee-cloud/functionality/account-and-billing)), then re-run it. Do not confuse it with `429`, which is transient throttling to back off on.

    `POST /api/v1/cognify` still returns the legacy body `{"error": "Token budget exhausted", "detail": "..."}` — see [Knowledge Processing](/cognee-cloud/functionality/knowledge-processing).
  </Accordion>

  <Accordion title="403 Forbidden">
    You are authenticated but lack the required permission on a dataset the request touches:

    ```json theme={null}
    {
      "detail": "Request owner does not have permission: [read] for any dataset. [PermissionDeniedError]"
    }
    ```

    The bracketed permission reflects the operation — `read` for search and recall, `write` for remember and improve, and `delete` as a separate grant. When you pass `datasets` or `dataset_ids`, every entry must be accessible: one inaccessible entry fails the whole request. See [Permissions and Access Control](/cognee-cloud/functionality/permissions-and-access-control).
  </Accordion>

  <Accordion title="404 Not Found">
    The route or resource does not exist. Check the `/api/v1/...` prefix, the HTTP method, and the resource id.

    `POST /api/v1/search` and `POST /api/v1/recall` resolve dataset names strictly: a name matching no dataset you own in the current tenant fails the whole request before any retrieval runs, listing every unresolved name. The other named datasets are not searched. Fix the name, or send `dataset_ids` with the UUID — a dataset shared with you is only reachable by UUID, never by name.
  </Accordion>

  <Accordion title="413 Request Entity Too Large">
    The add would push you past your workspace limits. Cognee Cloud caps each member at **1 GB** and **50,000 documents**, checked by `POST /api/v1/add` before anything is stored:

    ```json theme={null}
    {"detail": "Storage quota exceeded. Used: 1073500000 bytes, incoming: 2000000 bytes, limit: 1074000000 bytes."}
    ```

    The whole call is rejected and none of its files are stored, so retrying it unchanged fails the same way. Check `GET /api/v1/quotas/usage`, then delete data you no longer need or send fewer files per call. `POST /api/v1/remember` is not subject to these limits — see [Storage and document limits](/cognee-cloud/functionality/data-ingestion#storage-and-document-limits).
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You have hit a rate limit. Retry with backoff, spread large batches out instead of sending them at once, and build the retry into your client. Unlike `402`, this one clears on its own.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    A server-side failure. Retry with a smaller or simpler request to see whether the problem is data-specific, and check [Activity](/cognee-cloud/ui/activity) for the failed run. If it persists, bring the request and its timestamp to [Discord](https://discord.gg/m63hxKsp4p).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quick Start" href="/cognee-cloud/quickstart" icon="rocket">
    Upload data, build a graph, and search it in under five minutes.
  </Card>

  <Card title="Use the SDK instead" href="/cognee-cloud/connections/cloud-sdk" icon="code">
    Point a local Cognee process at your tenant and skip the HTTP layer.
  </Card>
</CardGroup>