Cognee Search API

openapi: 3.2.0
info:
  title: Cognee Search 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: Search
  description: Search endpoints for querying the knowledge graph.
paths:
  /api/v1/search:
    get:
      tags:
      - Search
      summary: List the caller's recent search history
      description: 'Get search history for the authenticated user.


        This endpoint retrieves the search history for the authenticated user,

        returning a list of previously executed searches with their timestamps.


        ## Response

        Returns a list of search history items containing:

        - **id**: Unique identifier for the search

        - **text**: The search query text

        - **user**: User who performed the search

        - **created_at**: When the search was performed


        ## Error Codes

        - **500 Internal Server Error**: Error retrieving search history'
      operationId: get_search_history_api_v1_search_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SearchHistoryItem'
                type: array
                title: Response Get Search History Api V1 Search Get
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
    post:
      tags:
      - Search
      summary: 'Search (low level): run one SearchType over the caller''s datasets'
      description: '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: HYBRID_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: Return what the LLM would have received instead of its answer. For completion type searches the result is the user prompt (conversation history, then question plus retrieval context through the retriever''s template, then the session guidance block); the system prompt (the retriever''s task template) is `system_prompt_result` with verbose=true. Retrieval-only types return their context. No LLM call is made.

        - **session_id** (Optional[str]): Session whose history and guidance feed the completion or the only_context prompt; the default session when omitted.

        - **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: true)

        - **code_query** (Optional[dict]): Structured operation arguments for CODE search


        ## Response

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


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

        - **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'
      operationId: search_api_v1_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPayloadDTO'
            example:
              search_type: GRAPH_COMPLETION
              query: What is Cognee?
              top_k: 10
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - items:
                    $ref: '#/components/schemas/SearchResult'
                  type: array
                - items: {}
                  type: array
                title: Response Search Api V1 Search Post
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    cognee__api__DTO__ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
      type: object
      required:
      - error
      title: ErrorResponse
      description: 'Error body returned by routers that answer 4xx/5xx themselves.


        ``error`` is the human-readable message. Errors raised as ``CogneeApiError`` are

        rendered instead by the app-level handler in ``cognee/api/client.py`` as

        ``{"detail": "<message> [<ErrorName>]"}`` plus ``"remediation"`` when a fix is known,

        and ``"code"``/``"param"`` when the error carries a stable reason (SearchType.CODE).'
    SearchHistoryItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        text:
          type: string
          title: Text
        user:
          type: string
          title: User
        createdAt:
          type: string
          format: date-time
          title: Createdat
        datasetId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Datasetid
      type: object
      required:
      - id
      - text
      - user
      - createdAt
      title: SearchHistoryItem
    SearchPayloadDTO:
      properties:
        searchType:
          $ref: '#/components/schemas/SearchType'
          description: 'Retrieval strategy. Common values: HYBRID_COMPLETION (default, passages + entities + LLM answer), GRAPH_COMPLETION (graph context + LLM answer), CODE (deterministic code graph), RAG_COMPLETION, CHUNKS, SUMMARIES, TEMPORAL, FEELING_LUCKY (auto-select), AGENTIC_COMPLETION (enables skills/tools/max_iter).'
          default: HYBRID_COMPLETION
        datasets:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Datasets
          description: Dataset names to search. Names only resolve to datasets owned by the caller; use dataset_ids for datasets shared with you.
          examples:
          - - default_dataset
        datasetIds:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Datasetids
          description: Dataset UUIDs to search (required for datasets shared with you). When provided, the datasets name list is ignored.
          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 nodes in these node_sets (the node_set values used during add/remember).
          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 the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is system_prompt_result with verbose=true. The session layer comes from session_id (the default session when omitted). Retrieval-only types return their context. No LLM call is made and nothing is written to the session.
          default: false
        sessionId:
          anyOf:
          - type: string
          - type: 'null'
          title: Sessionid
          description: Session whose history and guidance feed the completion (or the only_context prompt). Omit to use the default session.
          examples:
          - null
        verbose:
          type: boolean
          title: Verbose
          description: Return detailed result information including the graph representation when available.
          default: false
        skills:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Skills
          description: Skill names to load into the agentic retriever. Requires search_type=AGENTIC_COMPLETION; leave null otherwise.
          examples:
          - null
        tools:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tools
          description: Whitelist of tool names available to the agentic retriever. Requires search_type=AGENTIC_COMPLETION.
          examples:
          - null
        maxIter:
          anyOf:
          - type: integer
          - type: 'null'
          title: Maxiter
          description: Maximum agentic tool-call iterations before forcing a final answer (positive integer; AGENTIC_COMPLETION only).
          examples:
          - null
        includeReferences:
          type: boolean
          title: Includereferences
          description: Attach source references to completion-type results.
          default: false
        codeQuery:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Codequery
          description: Structured arguments for search_type=CODE. Set operation to query_facts, explore, traverse, find_path, impact_analysis, insights, architecture, delta, capabilities, search, neighbors, subgraph, flows, hubs, or ask (ask answers a natural-language question with seeds, flows, a one-hop neighbourhood and file:line citations). Add diagram='mermaid' (or 'dot', or true) to receive the result rendered as diagram source under search_result[0].diagram; architecture includes a Mermaid diagram unless diagram=false. A rejected request answers 422 with a stable 'code' (unknown_operation, invalid_argument, not_found, ambiguous, no_code_graph, feature_unavailable) and, when one argument is at fault, its 'param'.
      type: object
      required:
      - query
      title: SearchPayloadDTO
    SearchResult:
      properties:
        search_result:
          title: Search Result
        dataset_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Dataset Id
        dataset_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataset Name
      type: object
      required:
      - search_result
      - dataset_id
      - dataset_name
      title: SearchResult
    SearchType:
      type: string
      enum:
      - SUMMARIES
      - CHUNKS
      - RAG_COMPLETION
      - HYBRID_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
      - BROAD
      - SKILLS
      - TRIPLET_COMPLETION
      title: SearchType
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: auth_token
x-provenance:
  method: harvested
  publisher: Cognee
  source: https://docs.cognee.ai/cognee_openapi_spec.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)