OpenAPI Specification
openapi: 3.0.3
info:
title: Cognee REST agents search API
description: 'The Cognee REST API provides endpoints for the complete AI memory lifecycle, including data ingestion, knowledge graph construction, and semantic retrieval. Core endpoints cover adding raw text or documents, triggering the cognify pipeline that extracts entities and relationships via LLM, executing multi-mode search queries, managing datasets, and creating agent identities. The API uses X-Api-Key header authentication for cloud deployments and Bearer token auth for self-hosted instances.
'
version: 1.0.0
contact:
name: Cognee Support
url: https://docs.cognee.ai/api-reference/introduction
license:
name: Apache 2.0
url: https://github.com/topoteretes/cognee/blob/main/LICENSE
servers:
- url: https://api.cognee.ai
description: Cognee Cloud (managed)
- url: http://localhost:8000
description: Self-hosted (Docker / local)
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: search
description: Semantic and graph search queries
paths:
/api/v1/search:
get:
operationId: getSearchHistory
summary: Get search history for the authenticated user
description: 'Retrieves the search history for the authenticated user, returning a list of previously executed searches with their timestamps.
'
tags:
- search
security:
- BearerAuth: []
- ApiKeyAuth: []
responses:
'200':
description: List of search history items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SearchHistoryItem'
'403':
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: search
summary: Search the knowledge graph
description: 'Perform semantic search across the knowledge graph using one of 16 search types including GRAPH_COMPLETION, RAG_COMPLETION, SUMMARIES, CHUNKS, CYPHER, TEMPORAL, AGENTIC_COMPLETION and more. Supports dataset scoping and pagination.
'
tags:
- search
security:
- BearerAuth: []
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPayload'
example:
search_type: GRAPH_COMPLETION
query: What are the main topics in the research papers?
datasets:
- research_papers
top_k: 10
only_context: false
responses:
'200':
description: List of search results from the knowledge graph
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SearchResult'
'403':
description: Permission denied (returns empty list)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error or search prerequisites not met
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SearchResult:
type: object
description: A single result node from the knowledge graph
additionalProperties: true
SearchType:
type: string
enum:
- SUMMARIES
- CHUNKS
- RAG_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
description: Type of search to perform against the knowledge graph
ErrorResponse:
type: object
properties:
error:
type: string
description: Short error message
detail:
type: string
nullable: true
description: Detailed error description
required:
- error
SearchPayload:
type: object
required:
- query
properties:
search_type:
$ref: '#/components/schemas/SearchType'
default: GRAPH_COMPLETION
datasets:
type: array
items:
type: string
nullable: true
description: Dataset names to search (resolved to datasets owned by caller)
dataset_ids:
type: array
items:
type: string
format: uuid
nullable: true
description: Dataset UUIDs to search (allows cross-user access if permitted)
example: []
query:
type: string
description: The search query string
default: What is in the document?
system_prompt:
type: string
nullable: true
description: System prompt for completion-type searches
default: Answer the question using the provided context. Be as brief as possible.
node_name:
type: array
items:
type: string
nullable: true
description: Filter results to specific node_sets from the add pipeline
top_k:
type: integer
nullable: true
description: Maximum number of results to return
default: 10
only_context:
type: boolean
description: Return only context without LLM completion call
default: false
verbose:
type: boolean
description: Return verbose results
default: false
skills:
type: array
items:
type: string
nullable: true
description: Skills to enable for agentic search
tools:
type: array
items:
type: string
nullable: true
description: Tools to enable for agentic search
max_iter:
type: integer
nullable: true
description: Maximum iterations for agentic search
SearchHistoryItem:
type: object
properties:
id:
type: string
format: uuid
text:
type: string
user:
type: string
created_at:
type: string
format: date-time
required:
- id
- text
- user
- created_at
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token authentication for self-hosted instances
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
description: API key authentication for Cognee Cloud deployments
externalDocs:
description: Cognee API Reference
url: https://docs.cognee.ai/api-reference/introduction