Search

Search for nodes in the graph database.

This endpoint performs semantic search across the knowledge graph to find relevant nodes based on the provided query. It supports different search types and can be scoped to specific datasets.

Request Parameters

search_type (SearchType): Type of search to perform (default: GRAPH_COMPLETION). Use AGENTIC_COMPLETION to enable skills, tools and max_iter.
datasets (Optional[List[str]]): List of dataset names to search within
dataset_ids (Optional[List[UUID]]): List of dataset UUIDs to search within
query (str): The search query string
system_prompt Optional[str]: System prompt to be used for Completion type searches in Cognee
node_name Optional[list[str]]: Filter results to specific node_sets defined in the add pipeline (for targeted search).
top_k (Optional[int]): Maximum number of results to return (default: 15)
only_context bool: Set to true to only return context Cognee will be sending to LLM in Completion type searches. This will be returned instead of LLM calls for completion type searches.
verbose (bool): Return detailed result information including the graph representation when available (default: false)
skills (Optional[List[str]]): Skill names to load into the agentic retriever (AGENTIC_COMPLETION only)
tools (Optional[List[str]]): Tool whitelist for AGENTIC_COMPLETION searches
max_iter (Optional[int]): Max agentic iterations, must be >= 1 (AGENTIC_COMPLETION only)
include_references (bool): Attach source references to completion-type results (default: false)

Response

Returns a list of search results containing relevant nodes from the graph.

Error Codes

403 Forbidden: User lacks permission on the requested datasets (error body)
422 Unprocessable Content: Search prerequisites not met (run add + cognify first), or skills/tools sent without search_type=AGENTIC_COMPLETION, or max_iter < 1
500 Internal Server Error: Unexpected error during search

Notes

Datasets sent by name will only map to datasets owned by the request sender
To search datasets not owned by the request sender, dataset UUID is needed
If dataset_ids is provided, the datasets name list is ignored

POST

api

curl --request POST \
  --url https://api.cognee.ai/api/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_type": "GRAPH_COMPLETION",
  "query": "What is Cognee?",
  "top_k": 10
}
'

import requests

url = "https://api.cognee.ai/api/v1/search"

payload = {
    "search_type": "GRAPH_COMPLETION",
    "query": "What is Cognee?",
    "top_k": 10
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

[
  {
    "search_result": "<unknown>",
    "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "dataset_name": "<string>"
  }
]

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

searchType

enum<string>

default:GRAPH_COMPLETION

Retrieval strategy. Common values: GRAPH_COMPLETION (default, graph context + LLM answer), RAG_COMPLETION, CHUNKS, SUMMARIES, TEMPORAL, FEELING_LUCKY (auto-select), AGENTIC_COMPLETION (enables skills/tools/max_iter).

Available options:

SUMMARIES,

CHUNKS,

RAG_COMPLETION,

HYBRID_COMPLETION,

TRIPLET_COMPLETION,

GRAPH_COMPLETION,

GRAPH_COMPLETION_DECOMPOSITION,

GRAPH_SUMMARY_COMPLETION,

CYPHER,

NATURAL_LANGUAGE,

GRAPH_COMPLETION_COT,

GRAPH_COMPLETION_CONTEXT_EXTENSION,

FEELING_LUCKY,

TEMPORAL,

CODING_RULES,

CHUNKS_LEXICAL,

AGENTIC_COMPLETION

datasets

string[] | null

Dataset names to search. Names only resolve to datasets owned by the caller; use dataset_ids for datasets shared with you.

Example:

["default_dataset"]

datasetIds

string<uuid>[] | null

Dataset UUIDs to search (required for datasets shared with you). When provided, the datasets name list is ignored.

Example:

null

query

string

default:What is in the document?

systemPrompt

string | null

default:Answer the question using the provided context. Be as brief as possible.

nodeName

string[] | null

Restrict results to nodes in these node_sets (the node_set values used during add/remember).

Example:

null

topK

integer | null

default:15

onlyContext

boolean

default:false

verbose

boolean

default:false

Return detailed result information including the graph representation when available.

skills

string[] | null

Skill names to load into the agentic retriever. Requires search_type=AGENTIC_COMPLETION; leave null otherwise.

Example:

null

tools

string[] | null

Whitelist of tool names available to the agentic retriever. Requires search_type=AGENTIC_COMPLETION.

Example:

null

maxIter

integer | null

Maximum agentic tool-call iterations before forcing a final answer (positive integer; AGENTIC_COMPLETION only).

Example:

null

includeReferences

boolean

default:false

Attach source references to completion-type results.

Response

Successful Response

search_result

any

required

dataset_id

string<uuid> | null

required

dataset_name

string | null

required

Give Datasets Permission To PrincipalGrant permission on datasets to a principal (user or role). This endpoint allows granting specific permissions on one or more datasets to a principal (which can be a user or role). The authenticated user must have appropriate permissions to grant access to the specified datasets. ## Path Parameters - **principal_id** (UUID): The UUID of the principal (user or role) to grant permission to ## Request Parameters - **permission_name** (str, query): Permission to grant. One of "read", "write", "delete", "share". - **dataset_ids** (List[UUID], JSON body): Array of dataset UUIDs to grant permission on. ## Response Returns a success message indicating permission was assigned. ## Error Codes - **400 Bad Request**: Invalid request parameters - **403 Forbidden**: User doesn't have permission to grant access - **500 Internal Server Error**: Error granting permission

⌘I

curl --request POST \
  --url https://api.cognee.ai/api/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_type": "GRAPH_COMPLETION",
  "query": "What is Cognee?",
  "top_k": 10
}
'

import requests

url = "https://api.cognee.ai/api/v1/search"

payload = {
    "search_type": "GRAPH_COMPLETION",
    "query": "What is Cognee?",
    "top_k": 10
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

[
  {
    "search_result": "<unknown>",
    "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "dataset_name": "<string>"
  }
]

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}