Cognee Cloud HTTP API - Cognee Documentation

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.

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 page — your-tenant is a placeholder, not a live host.

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.

Authentication

All requests carry your API key in a header:

X-Api-Key: YOUR-API-KEY
X-Tenant-Id: YOUR-TENANT
Content-Type: application/json

Create and copy keys on the 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

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

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

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.

Core endpoints

Data Ingestion

POST /api/v1/addAdd text, documents, or structured data to a dataset.

Knowledge Processing

POST /api/v1/cognifyTurn ingested data into a knowledge graph of entities and relationships.

Ingest and Process

POST /api/v1/rememberDo both in one call, with control over chunking, ontologies, and the graph model.

Search

POST /api/v1/searchQuery the graph in natural language. Pick a search_type to trade depth for latency — see Search and Recall.

Dataset Management

/api/v1/datasets/*List datasets, inspect their contents, and delete a data item or a whole dataset. See Dataset Management.

Recall

POST /api/v1/recallRetrieve memory for an agent turn, including session context. See Search and Recall.

Trying a request from these docs

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

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.
Add your X-Api-Key.

Swagger UI is available too: the shared docs at 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:

{
  "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.

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.

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

402 Payment Required

The token budget for the request is exhausted, on either the LLM or the embedding path:

{
  "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), 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.

403 Forbidden

You are authenticated but lack the required permission on a dataset the request touches:

{
  "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.

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.

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:

{"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.

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.

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 for the failed run. If it persists, bring the request and its timestamp to Discord.

​Base URL

​Authentication

​Quick example

​Core endpoints

Data Ingestion

Knowledge Processing

Ingest and Process

Search

Dataset Management

Recall

​Trying a request from these docs

​Error handling

​Next steps

Quick Start

Use the SDK instead

Base URL

Authentication

Quick example

Core endpoints

Trying a request from these docs

Error handling

Next steps