> ## 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. # Recall: query memory with auto-routed search type and session-first lookup > Recall information from the knowledge graph. This is a memory-oriented alias for the search endpoint. All search types and options from v1 are supported. ## Request Parameters Field names are shown camelCased in the schema (e.g. searchType, datasetIds, topK); both camelCase and snake_case are accepted. - **search_type** (Optional[SearchType]): Type of search to perform. Omit (default: null) to auto-route the query with the rule-based router (HYBRID_COMPLETION fallback); pass a value to pin one. - **datasets** (Optional[List[str]]): Dataset names to search within - **dataset_ids** (Optional[List[UUID]]): Dataset UUIDs to search within; take precedence over dataset names when both are provided - **query** (str): The search query string - **system_prompt** (Optional[str]): System prompt for completion searches - **node_name** (Optional[List[str]]): Filter to specific node sets - **top_k** (Optional[int]): Maximum results (default: 15) - **only_context** (bool): Return what the LLM would have received instead of its answer — for completion types each item's text is the user prompt (conversation history, question plus retrieval context, session guidance) and its system_prompt field the retriever's task template; retrieval-only types return their context - **verbose** (bool): Verbose output - **include_references** (bool): Include source/provenance references in completion results (default: true) - **stream** (Optional[bool]): Stream the answer as server-sent events (`text/event-stream`). Defaults to content negotiation on `Accept`. - **session_id** (Optional[str]): Session whose cached QA and trace entries should be searched - **scope** (Optional[str | List[str]]): Memory sources to include: "graph", "session", "session_first", "trace", "session_context", "tools", "code", "all", "auto", or a list of these (default: "auto" — session first when session_id is set, else graph). "session_first" requests that short-circuit explicitly rather than by omitting searchType. "code" is explicit opt-in only and returns deterministic code-graph facts tagged source="code" (e.g. scope=["graph", "code"]) - **code_query** (Optional[dict]): "code" scope only — operation and arguments for the code-graph query (same format as /v1/search code_query); omit for the default "explore" with the query text as seed - **response_schema** (Optional[dict]): JSON Schema for structured completion output; validated results land in each result's ``structured`` field. 422 on schemas outside the supported subset. - **contextProfile** (str): Profile to render for the 'session_context' scope: 'qa' (conversational) or 'agent' (tool/workflow). Ignored by other scopes. Defaults to 'qa'. - **toolConnections** (Optional[List[str]]): Names of authorized external database connections for the 'tools' scope. Omit to use every connection visible to the caller. - **toolsTrigger** (str): When the 'tools' scope runs: 'always', or 'on_empty' to query the external database only when every other requested source returned nothing. Defaults to 'always'. ## Error Codes - **402/403/404/409/422**: Cognee errors (payment required, permission denied, missing user, session-dataset conflict, prerequisites not met) return their own status code and message via the global error handler - **409 Conflict**: Unexpected non-Cognee error during recall ## OpenAPI ````yaml /cognee_openapi_spec.json post /api/v1/recall openapi: 3.1.0 info: title: Cognee API description: Cognee API with Bearer token and Cookie auth version: 1.0.0 servers: - url: https://{tenant}.aws.cognee.ai description: 'Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard' variables: tenant: default: your-tenant description: Your tenant name, shown in the Cognee Cloud dashboard - url: http://localhost:8000 description: 'Self-hosted: a locally running cognee server' security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: activity description: >- Activity endpoints for inspecting pipeline runs, traced spans, tenant users, agents, and dataset exports. - name: add description: Data ingestion endpoints for adding text, files, and structured data. - name: agent connections description: >- Endpoints for registering, unregistering, and inspecting agent connections to the instance. - name: agent management description: Endpoints for creating, listing, retrieving, and deleting agents. - name: auth description: >- Authentication endpoints for user registration, login, and token management. - name: checks description: >- Diagnostic endpoint for validating a Cognee Cloud API key supplied in the X-Api-Key header. - name: cognify description: >- Knowledge processing endpoints to transform raw data into knowledge graphs. - name: configuration description: >- Endpoints for storing, retrieving, and listing a user's saved configurations. - name: datasets description: Dataset management endpoints for listing, creating, and deleting datasets. - name: delete description: Data deletion endpoints (deprecated — use datasets endpoints instead). - name: forget description: Endpoint for removing data from the knowledge graph. - name: health description: Liveness, readiness, and component health checks. - name: improve description: Endpoint for enriching and improving an existing knowledge graph. - name: integrations description: >- Endpoints for connecting, provisioning, and disconnecting OAuth providers and plugins. - name: llm description: >- LLM-backed endpoints for inferring graph schemas and generating custom extraction prompts. - name: memify description: >- Endpoint for running enrichment pipelines over existing graphs or supplied data. - name: ontologies description: >- Endpoints for uploading, listing, and deleting ontology files used during cognify. - name: permissions description: Permission management for multi-user access control. - name: recall description: >- Endpoints for querying the knowledge graph and reviewing past recall history. - name: remember description: >- Endpoints for ingesting data into the knowledge graph and storing session memory entries. - name: responses description: Response generation endpoints using the knowledge graph. - name: schema description: >- Schema inspection endpoints for a dataset's derived schema inventory and the caller-wide memory provenance graph. - name: search description: Search endpoints for querying the knowledge graph. - name: sessions description: >- Endpoints for listing sessions and reporting usage, cost, and token statistics. - name: settings description: Configuration endpoints for managing Cognee settings. - name: skills description: >- Skill management endpoints for ingesting, listing, retrieving, and deleting dataset skills, plus read-only retrieval of improvement proposals. - name: slack description: >- Endpoints for listing workspace channels, setting channel allowlists, and linking Slack accounts. - name: sync description: Endpoints for syncing local data to Cognee Cloud and checking sync status. - name: update description: Endpoint for updating existing data in a dataset. - name: users description: User management endpoints. - name: validate description: >- Diagnostic endpoint for checking consistency between a dataset's graph and vector stores. - name: visualize description: Graph visualization endpoints. paths: /api/v1/recall: post: tags: - recall summary: >- Recall: query memory with auto-routed search type and session-first lookup description: >- Recall information from the knowledge graph. This is a memory-oriented alias for the search endpoint. All search types and options from v1 are supported. ## Request Parameters Field names are shown camelCased in the schema (e.g. searchType, datasetIds, topK); both camelCase and snake_case are accepted. - **search_type** (Optional[SearchType]): Type of search to perform. Omit (default: null) to auto-route the query with the rule-based router (HYBRID_COMPLETION fallback); pass a value to pin one. - **datasets** (Optional[List[str]]): Dataset names to search within - **dataset_ids** (Optional[List[UUID]]): Dataset UUIDs to search within; take precedence over dataset names when both are provided - **query** (str): The search query string - **system_prompt** (Optional[str]): System prompt for completion searches - **node_name** (Optional[List[str]]): Filter to specific node sets - **top_k** (Optional[int]): Maximum results (default: 15) - **only_context** (bool): Return what the LLM would have received instead of its answer — for completion types each item's text is the user prompt (conversation history, question plus retrieval context, session guidance) and its system_prompt field the retriever's task template; retrieval-only types return their context - **verbose** (bool): Verbose output - **include_references** (bool): Include source/provenance references in completion results (default: true) - **stream** (Optional[bool]): Stream the answer as server-sent events (`text/event-stream`). Defaults to content negotiation on `Accept`. - **session_id** (Optional[str]): Session whose cached QA and trace entries should be searched - **scope** (Optional[str | List[str]]): Memory sources to include: "graph", "session", "session_first", "trace", "session_context", "tools", "code", "all", "auto", or a list of these (default: "auto" — session first when session_id is set, else graph). "session_first" requests that short-circuit explicitly rather than by omitting searchType. "code" is explicit opt-in only and returns deterministic code-graph facts tagged source="code" (e.g. scope=["graph", "code"]) - **code_query** (Optional[dict]): "code" scope only — operation and arguments for the code-graph query (same format as /v1/search code_query); omit for the default "explore" with the query text as seed - **response_schema** (Optional[dict]): JSON Schema for structured completion output; validated results land in each result's ``structured`` field. 422 on schemas outside the supported subset. - **contextProfile** (str): Profile to render for the 'session_context' scope: 'qa' (conversational) or 'agent' (tool/workflow). Ignored by other scopes. Defaults to 'qa'. - **toolConnections** (Optional[List[str]]): Names of authorized external database connections for the 'tools' scope. Omit to use every connection visible to the caller. - **toolsTrigger** (str): When the 'tools' scope runs: 'always', or 'on_empty' to query the external database only when every other requested source returned nothing. Defaults to 'always'. ## Error Codes - **402/403/404/409/422**: Cognee errors (payment required, permission denied, missing user, session-dataset conflict, prerequisites not met) return their own status code and message via the global error handler - **409 Conflict**: Unexpected non-Cognee error during recall operationId: recall_api_v1_recall_post requestBody: content: application/json: schema: $ref: '#/components/schemas/RecallPayloadDTO' required: true responses: '200': description: Successful Response content: application/json: schema: items: oneOf: - $ref: '#/components/schemas/ResponseQAEntry' - $ref: '#/components/schemas/ResponseAgentTraceEntry' - $ref: '#/components/schemas/ResponseSessionContextEntry' - $ref: '#/components/schemas/ResponseGraphEntry' - $ref: '#/components/schemas/ResponseCodeEntry' - $ref: '#/components/schemas/ResponseToolEntry' - $ref: '#/components/schemas/ResponseSkillEntry' - $ref: '#/components/schemas/ResponseMarkerEntry' discriminator: propertyName: source mapping: session: $ref: '#/components/schemas/ResponseQAEntry' trace: $ref: '#/components/schemas/ResponseAgentTraceEntry' session_context: $ref: '#/components/schemas/ResponseSessionContextEntry' graph: $ref: '#/components/schemas/ResponseGraphEntry' code: $ref: '#/components/schemas/ResponseCodeEntry' tools: $ref: '#/components/schemas/ResponseToolEntry' skills: $ref: '#/components/schemas/ResponseSkillEntry' system: $ref: '#/components/schemas/ResponseMarkerEntry' type: array title: Response Recall Api V1 Recall Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: RecallPayloadDTO: properties: searchType: anyOf: - $ref: '#/components/schemas/SearchType' - type: 'null' description: >- Search strategy, e.g. HYBRID_COMPLETION, GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS. Omit (or pass null) to let cognee auto-route the query (rule-based, no LLM call, HYBRID_COMPLETION fallback; see docs/recall-vs-search.md for the rule table). Pass a value to pin one. datasets: anyOf: - items: type: string type: array - type: 'null' title: Datasets description: >- Dataset names to search within. Omit (null) to search all datasets you have read access to. examples: - - default_dataset datasetIds: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Datasetids description: >- Dataset UUIDs to search within; takes precedence over 'datasets' names when both are provided. Leave empty to resolve by name. examples: - null query: type: string title: Query description: The question to answer. Required; there is no default query. examples: - What is in the document? systemPrompt: anyOf: - type: string - type: 'null' title: Systemprompt default: >- Answer the question using the provided context. Be as brief as possible. nodeName: anyOf: - items: type: string type: array - type: 'null' title: Nodename description: >- Restrict results to these node sets (the node_set values passed to /v1/add or /v1/remember). Omit to search all nodes. examples: - null topK: anyOf: - type: integer - type: 'null' title: Topk default: 15 onlyContext: type: boolean title: Onlycontext description: >- Return what the LLM would have received instead of its answer. For completion search types each item's text is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block) and its system_prompt field carries the retriever's task template. Retrieval-only types return their context. No LLM call is made and nothing is written to the session. default: false verbose: type: boolean title: Verbose default: false includeReferences: type: boolean title: Includereferences description: Include source/provenance references in completion results. default: false sessionId: anyOf: - type: string - type: 'null' title: Sessionid description: >- Session whose cached QA and trace entries should be searched. With search_type omitted the session becomes a search source: alone it short-circuits the graph on a hit, alongside datasets both contribute. Pinning search_type leaves the graph as the only source. examples: - null scope: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scope description: >- Which memory sources to include: 'graph', 'session', 'session_first', 'trace', 'session_context', 'tools', 'code', 'all', 'auto', or a list of these. Defaults to 'auto' (session first when session_id is set, else graph). 'session_first' asks for that short-circuit explicitly — a session hit answers alone — instead of getting it by omitting search_type. 'tools' and 'code' are explicit opt-in only — never implied by 'auto' or 'all'. 'tools' requires TOOL_CALLS_ENABLED on the server; 'code' runs a deterministic code-graph query (see code_query) and tags results source='code'. examples: - null toolConnections: anyOf: - items: type: string type: array - type: 'null' title: Toolconnections description: >- Names of authorized external database connections for the 'tools' scope. Omit to use every connection visible to the caller. examples: - null stream: anyOf: - type: boolean - type: 'null' title: Stream description: >- Stream the answer as server-sent events. When omitted, the `Accept` header decides: streaming happens only for a client that ranks `text/event-stream` above `application/json`, so `*/*` and the two listed together both stay on the JSON response. toolsTrigger: type: string title: Toolstrigger description: >- When the 'tools' scope runs: 'always', or 'on_empty' to query the external database only when every other requested source returned nothing. default: always codeQuery: anyOf: - additionalProperties: true type: object - type: 'null' title: Codequery description: >- 'code' scope only: structured operation and arguments for the deterministic code-graph query (same format as /v1/search code_query, e.g. \{"operation": "impact_analysis", "seeds": ["UserService"]\}). Omit to run the default 'explore' operation with the query text as seed. A seed the code graph cannot resolve contributes no results rather than failing the recall. examples: - null contextProfile: type: string title: Contextprofile description: >- Profile to render for the 'session_context' scope: 'qa' (conversational) or 'agent' (tool/workflow). Ignored by other scopes. default: qa responseSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Responseschema description: >- JSON Schema for structured completion output (typically MyModel.model_json_schema()). The completion is validated against it and each result carries the validated payload in its 'structured' field. Supported by completion-style search types only. Structural subset: objects, primitives, arrays, enums, optionals, $defs references; value constraints (minLength, ...) are not enforced server-side. examples: - null type: object required: - query title: RecallPayloadDTO ResponseQAEntry: properties: time: type: string title: Time question: type: string title: Question context: type: string title: Context answer: type: string title: Answer qa_id: anyOf: - type: string - type: 'null' title: Qa Id feedback_text: anyOf: - type: string - type: 'null' title: Feedback Text feedback_score: anyOf: - type: integer - type: 'null' title: Feedback Score used_graph_element_ids: anyOf: - additionalProperties: items: type: string type: array type: object - type: 'null' title: Used Graph Element Ids memify_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Memify Metadata used_session_context_ids: anyOf: - items: type: string type: array - type: 'null' title: Used Session Context Ids source: type: string const: session title: Source type: object required: - time - question - context - answer - source title: ResponseQAEntry ResponseAgentTraceEntry: properties: trace_id: type: string title: Trace Id origin_function: type: string title: Origin Function status: type: string title: Status memory_query: type: string title: Memory Query default: '' memory_context: type: string title: Memory Context default: '' method_params: additionalProperties: true type: object title: Method Params method_return_value: title: Method Return Value error_message: type: string title: Error Message default: '' session_feedback: type: string title: Session Feedback default: '' source: type: string const: trace title: Source type: object required: - trace_id - origin_function - status - source title: ResponseAgentTraceEntry ResponseSessionContextEntry: properties: source: type: string const: session_context title: Source content: type: string title: Content context_profile: type: string title: Context Profile type: object required: - source - content - context_profile title: ResponseSessionContextEntry ResponseGraphEntry: properties: kind: $ref: '#/components/schemas/SearchResultKind' search_type: $ref: '#/components/schemas/SearchType' text: type: string title: Text system_prompt: anyOf: - type: string - type: 'null' title: System Prompt score: anyOf: - type: number - type: 'null' title: Score dataset_id: anyOf: - type: string - type: 'null' title: Dataset Id dataset_name: anyOf: - type: string - type: 'null' title: Dataset Name metadata: additionalProperties: true type: object title: Metadata default: {} raw: additionalProperties: true type: object title: Raw default: {} structured: anyOf: - {} - type: 'null' title: Structured source: type: string const: graph title: Source type: object required: - kind - search_type - text - source title: ResponseGraphEntry ResponseCodeEntry: properties: kind: $ref: '#/components/schemas/SearchResultKind' search_type: $ref: '#/components/schemas/SearchType' text: type: string title: Text system_prompt: anyOf: - type: string - type: 'null' title: System Prompt score: anyOf: - type: number - type: 'null' title: Score dataset_id: anyOf: - type: string - type: 'null' title: Dataset Id dataset_name: anyOf: - type: string - type: 'null' title: Dataset Name metadata: additionalProperties: true type: object title: Metadata default: {} raw: additionalProperties: true type: object title: Raw default: {} structured: anyOf: - {} - type: 'null' title: Structured source: type: string const: code title: Source type: object required: - kind - search_type - text - source title: ResponseCodeEntry description: |- One deterministic code-graph fact from the recall "code" scope. Same normalized shape as graph entries (kind CODE, payload under ``raw``) — only the source discriminator differs, so callers can route code facts separately from semantic graph results. ResponseToolEntry: properties: source: type: string const: tools title: Source tool_name: type: string title: Tool Name question: type: string title: Question text: type: string title: Text success: type: boolean title: Success default: true error: anyOf: - type: string - type: 'null' title: Error structured: anyOf: - additionalProperties: true type: object - type: 'null' title: Structured type: object required: - source - tool_name - question - text title: ResponseToolEntry description: |- One tool invocation's result from the recall "tools" scope. Generic across tools: ``tool_name`` discriminates the tool (only ``text_to_sql`` in v1) and ``structured`` carries the tool-specific payload, so adding a tool never changes this union. Secrets (connection strings) never appear here. ResponseSkillEntry: properties: source: type: string const: skills title: Source text: type: string title: Text skill: additionalProperties: true type: object title: Skill score: anyOf: - type: number - type: 'null' title: Score type: object required: - source - text - skill title: ResponseSkillEntry description: >- One skill surfaced by the deterministic skill gate. Metadata-only: ``skill`` carries the projected Skill fields and never the procedure body — progressive disclosure keeps bodies behind the ``load_skill`` tool or ``GET /skills/{skill_id}``. ``text`` is a renderable "name: description" line; ``score`` is the raw vector distance (lower is better) when available. ResponseMarkerEntry: properties: source: type: string const: system title: Source status: type: string title: Status text: type: string title: Text datapoint_count: type: integer title: Datapoint Count threshold: type: integer title: Threshold error_class: anyOf: - type: string - type: 'null' title: Error Class error_message: anyOf: - type: string - type: 'null' title: Error Message type: object required: - source - status - text - datapoint_count - threshold title: ResponseMarkerEntry description: |- System-generated marker (not data), e.g. "memory still warming up". ``text`` carries a human-readable message so generic consumers that fall back to text rendering display something sensible. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SearchType: type: string enum: - 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 - CODE - GRAPH_REPORT - SKILLS title: SearchType SearchResultKind: type: string enum: - graph_completion - rag_completion - triplet_completion - cypher - chunk - summary - coding_rule - code - skill - natural_language - temporal - structured - unknown title: SearchResultKind description: |- Semantic kind of a search result item. More precise than ``search_type`` alone — tells the caller which normalization shape was applied. LLM completion types all collapse to ``*_COMPLETION`` kinds; non-LLM retrievers produce structural kinds (``CHUNK``, ``SUMMARY``, ``CYPHER`` row). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````