Cognee Visualize API

openapi: 3.2.0
info:
  title: Cognee Visualize 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: visualize
  description: Graph visualization endpoints.
paths:
  /api/v1/visualize:
    get:
      tags:
      - visualize
      summary: Visualize
      description: 'Generate an HTML visualization of the dataset''s knowledge graph.


        By default renders a bounded subgraph around relevant seed nodes; pass

        ``full=true`` to render the entire graph (legacy behavior). Seeds come

        from ``query`` or ``seed_node_ids`` when given, otherwise the graph''s

        highest-degree nodes.


        ## Query Parameters

        - **dataset_id** (UUID): The unique identifier of the dataset to visualize

        - **full** (bool): Render the full graph when true

        - **query** (str): Query string to seed the subgraph via vector search

        - **seed_node_ids** (list[str]): Explicit seed node ids

        - **neighborhood_depth** (int): k-hop expansion depth (default 2)

        - **neighborhood_seed_top_k** (int): Max seeds (default 10)

        - **max_nodes** (int): Node cap after expansion (default 500)


        ## Response

        Returns an HTML page containing the interactive graph visualization.


        ## Error Codes

        - **409 Conflict**: Dataset not found, permission denied, or visualization

        failed (detail in the `error` field)


        ## Notes

        - User must have read permissions on the dataset

        - Visualization is interactive and allows graph exploration'
      operationId: visualize_api_v1_visualize_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: dataset_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
          examples:
          - ''
          title: Dataset Id
        description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
      - name: full
        in: query
        required: false
        schema:
          type: boolean
          description: Render the entire graph instead of a bounded subgraph.
          default: false
          title: Full
        description: Render the entire graph instead of a bounded subgraph.
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query string whose nearest vector hits seed the subgraph.
          title: Query
        description: Query string whose nearest vector hits seed the subgraph.
      - name: seed_node_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Explicit seed node ids for subgraph neighborhood expansion.
          title: Seed Node Ids
        description: Explicit seed node ids for subgraph neighborhood expansion.
      - name: neighborhood_depth
        in: query
        required: false
        schema:
          type: integer
          maximum: 10
          minimum: 1
          description: k-hop neighborhood depth for subgraph expansion.
          default: 2
          title: Neighborhood Depth
        description: k-hop neighborhood depth for subgraph expansion.
      - name: neighborhood_seed_top_k
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of seed nodes.
          default: 10
          title: Neighborhood Seed Top K
        description: Maximum number of seed nodes.
      - name: max_nodes
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          description: Hard cap on rendered nodes after expansion.
          default: 500
          title: Max Nodes
        description: Hard cap on rendered nodes after expansion.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/visualize/json:
    get:
      tags:
      - visualize
      summary: Visualize Json
      description: 'Return the dataset''s knowledge graph as a JSON-safe payload.


        Same authorization, dataset resolution and bounded fetch as `GET

        /visualize` — pass the same arguments to get the JSON behind the

        same subgraph the HTML page would have shown. Does not include the

        semantic layout; see `GET /visualize/semantic` for that, computed

        separately so a client that never opens the semantic tab never pays

        for it.


        ## Query Parameters

        Same as `GET /visualize` (dataset_id, full, query, seed_node_ids,

        neighborhood_depth, neighborhood_seed_top_k, max_nodes), plus

        `stream` and `include_session_events`.


        ## Response

        A JSON object with `nodes`, `links`, `color_maps`, `schema_graph`,

        `schema_data`, `pipeline_stages`, `edge_classes`, `bundles`,

        `provenance_index`, `has_meaningful_topological_rank`, `memory_map`

        and `search_events` (empty when `include_session_events=false`).


        ## Streaming

        Sent when the request has `Accept: text/event-stream` or

        `stream=true`, for graphs too large for one response. Events:

        `meta` (seeds, seed source, bounds); one `chunk` per read, with

        compact `nodes` (id, name, type, stage, is_unnamed, belongs_to_set,

        source_node_set) and `links` (source, target, relation, edge_class)

        whose endpoints were all sent in this or an earlier chunk; `summary`

        (`importance` and `label_priority` per node, split into events of at

        most one chunk''s size, the first also carrying `color_maps.node_set`);

        `done` (totals). A failure after the response started is one

        `error` event with `message` and `status`. The heavy side payloads

        are not streamed, and `full=true` cannot be streamed. A stream never

        carries `search_events` regardless of `include_session_events`; the

        Memory tab gets that history from `/visualize/live-events` instead.


        ## Error Codes

        - **409 Conflict**: Dataset not found, permission denied, or the

        payload could not be built (generic message; full detail is

        server-logged, not returned, to avoid leaking internals)

        - **Request validation error** (400 on the cognee server, like any

        invalid parameter): `max_nodes` above 5000 without streaming, or

        `full=true` with streaming

        - **503 Service Unavailable**: streamed, and this server already has

        its maximum number of graph streams open; retry shortly


        ## Notes

        - User must have read permissions on the dataset'
      operationId: visualize_json_api_v1_visualize_json_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: dataset_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
          examples:
          - ''
          title: Dataset Id
        description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
      - name: full
        in: query
        required: false
        schema:
          type: boolean
          description: Include the entire graph instead of a bounded subgraph.
          default: false
          title: Full
        description: Include the entire graph instead of a bounded subgraph.
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query string whose nearest vector hits seed the subgraph.
          title: Query
        description: Query string whose nearest vector hits seed the subgraph.
      - name: seed_node_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Explicit seed node ids for subgraph neighborhood expansion.
          title: Seed Node Ids
        description: Explicit seed node ids for subgraph neighborhood expansion.
      - name: neighborhood_depth
        in: query
        required: false
        schema:
          type: integer
          maximum: 10
          minimum: 1
          description: k-hop neighborhood depth for subgraph expansion.
          default: 2
          title: Neighborhood Depth
        description: k-hop neighborhood depth for subgraph expansion.
      - name: neighborhood_seed_top_k
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of seed nodes.
          default: 10
          title: Neighborhood Seed Top K
        description: Maximum number of seed nodes.
      - name: max_nodes
        in: query
        required: false
        schema:
          type: integer
          maximum: 20000
          minimum: 1
          description: Hard cap on rendered nodes after expansion. Up to 5000 as JSON, up to 20000 when streamed.
          default: 500
          title: Max Nodes
        description: Hard cap on rendered nodes after expansion. Up to 5000 as JSON, up to 20000 when streamed.
      - name: stream
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Stream the graph as server-sent events. Defaults to content negotiation on `Accept`; true or false decides outright.
          title: Stream
        description: Stream the graph as server-sent events. Defaults to content negotiation on `Accept`; true or false decides outright.
      - name: include_session_events
        in: query
        required: false
        schema:
          type: boolean
          description: Include the dataset's search/improve history as `search_events`. Defaults to true; a client that reads that history elsewhere (e.g. `/visualize/live-events`) can pass false to skip collecting it.
          default: true
          title: Include Session Events
        description: Include the dataset's search/improve history as `search_events`. Defaults to true; a client that reads that history elsewhere (e.g. `/visualize/live-events`) can pass false to skip collecting it.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/visualize/semantic:
    get:
      tags:
      - visualize
      summary: Visualize Semantic
      description: 'Return semantic positions and clusters for the same subgraph as `GET /visualize/json`.


        Pass the same arguments used for `GET /visualize/json` to lay out the

        same subgraph semantically. This is the one call that fetches

        embeddings (up to 2000 nodes) and runs PCA/UMAP over them, so it is

        only worth calling when the semantic tab is actually open.


        ## Query Parameters

        Same as `GET /visualize/json`.

        - **dataset_id** (UUID): UUID of the dataset to visualize. List your datasets via GET

        /api/v1/datasets to find it.

        - **full** (bool): Include the entire graph instead of a bounded subgraph. Defaults to

        False.

        - **max_nodes** (int): Hard cap on rendered nodes after expansion. Defaults to 500.

        - **neighborhood_depth** (int): k-hop neighborhood depth for subgraph expansion. Defaults to

        2.

        - **neighborhood_seed_top_k** (int): Maximum number of seed nodes. Defaults to 10.

        - **query** (Optional[str]): Query string whose nearest vector hits seed the subgraph.

        - **seed_node_ids** (Optional[List[str]]): Explicit seed node ids for subgraph neighborhood

        expansion.


        ## Response

        A JSON object with `semantic_positions` and `semantic_clusters`,

        either of which is `null` when there are no embeddings to lay out.


        ## Error Codes

        - **409 Conflict**: Dataset not found, permission denied, or the

        payload could not be built (generic message; full detail is

        server-logged, not returned, to avoid leaking internals)


        ## Notes

        - User must have read permissions on the dataset'
      operationId: visualize_semantic_api_v1_visualize_semantic_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: dataset_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
          examples:
          - ''
          title: Dataset Id
        description: UUID of the dataset to visualize. List your datasets via GET /api/v1/datasets to find it.
      - name: full
        in: query
        required: false
        schema:
          type: boolean
          description: Include the entire graph instead of a bounded subgraph.
          default: false
          title: Full
        description: Include the entire graph instead of a bounded subgraph.
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query string whose nearest vector hits seed the subgraph.
          title: Query
        description: Query string whose nearest vector hits seed the subgraph.
      - name: seed_node_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Explicit seed node ids for subgraph neighborhood expansion.
          title: Seed Node Ids
        description: Explicit seed node ids for subgraph neighborhood expansion.
      - name: neighborhood_depth
        in: query
        required: false
        schema:
          type: integer
          maximum: 10
          minimum: 1
          description: k-hop neighborhood depth for subgraph expansion.
          default: 2
          title: Neighborhood Depth
        description: k-hop neighborhood depth for subgraph expansion.
      - name: neighborhood_seed_top_k
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of seed nodes.
          default: 10
          title: Neighborhood Seed Top K
        description: Maximum number of seed nodes.
      - name: max_nodes
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          description: Hard cap on rendered nodes after expansion.
          default: 500
          title: Max Nodes
        description: Hard cap on rendered nodes after expansion.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/visualize/brains:
    get:
      tags:
      - visualize
      summary: Visualize Brains
      description: 'Return every dataset the caller may read, each as a small graph preview.


        No `dataset_id`: this is the Brains overview, not one brain. Built on

        the same union CLO-399 already uses to decide which datasets a user

        can see — their own, their tenant''s, and anything granted to a role

        they belong to — so a dataset shared with a group appears here with

        no separate authorization logic.


        ## Query Parameters

        - **max_nodes** (int): Node cap applied independently to each

        dataset (default 500) — there is no larger, separate cap for "all

        datasets at once".


        ## Response

        `{dataset_id: {"name", "nodes", "links", "node_set_colors"}}`.


        ## Notes

        - Only datasets the caller has read permission on are included'
      operationId: visualize_brains_api_v1_visualize_brains_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: max_nodes
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          description: Hard cap on rendered nodes per dataset.
          default: 500
          title: Max Nodes
        description: Hard cap on rendered nodes per dataset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/visualize/brains-summary:
    get:
      tags:
      - visualize
      summary: Visualize Brains Summary
      description: 'Return every dataset the caller may read, described from relational metadata.


        The cheap counterpart of `GET /visualize/brains`: the same datasets,

        but only what an overview shows — name, sources, size, colors — built

        from relational metadata and the per-cognify-run count cache instead

        of one bounded graph read per dataset. The cost is one count query per

        cognify run whose count is not cached yet, not a graph fetch per

        dataset on every call, so a cold cache pays once per run and every

        later call pays nothing. `/brains` stays the call to make when the

        node and link arrays themselves are needed.


        ## Response

        `{dataset_id: {"name", "source_names", "node_count", "node_set_colors"}}`:

        - **name** (str): the dataset''s name

        - **source_names** (list[str]): its distinct node set names, sorted;

        empty when the data was ingested without node sets

        - **node_count** (int): nodes in the dataset''s graph as of its latest

        cognify run — the whole graph, not only entity nodes, and 0 for a

        dataset that has never been cognified. A 0 also stands in for a graph

        that could not be read; this payload cannot distinguish the two, so

        use `GET /datasets/graph-summary` and its `computedAt` when that

        matters

        - **node_set_colors** (dict[str, str]): node set colors from the same

        rule `/brains` uses. Same rule and same node sets give the same

        colors, but the two endpoints can be looking at different node

        sets — `/brains` takes them from a bounded graph fetch (and so sees

        sets that exist only in the graph), this takes them from a full

        relational scan — and where the sets differ the colors do too


        ## Error Codes

        - **409 Conflict**: Payload could not be built (generic message; full

        detail is server-logged, not returned, to avoid leaking internals)


        ## Notes

        - Only datasets the caller has read permission on are included'
      operationId: visualize_brains_summary_api_v1_visualize_brains_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
  /api/v1/visualize/live-events:
    get:
      tags:
      - visualize
      summary: Visualize Live Events
      description: 'Return search/improve events newer than a cursor, for the Memory tab''s live timeline.


        Meant to be polled instead of re-fetching the whole `GET

        /visualize/json` payload just to refresh the timeline: pass the

        previous response''s `cursor` back as `since` and only new events

        come back. The filter is strict, so nothing is ever delivered twice.


        ## Query Parameters

        - **dataset_id** (UUID): authorization and event scope, see above

        - **since** (datetime, optional): cursor from a previous call


        ## Response

        `{"events": [...], "cursor": }`


        ## Error Codes

        - **403 Forbidden**: Caller lacks read permission on the dataset (or

        it does not exist)

        - **409 Conflict**: Payload could not be built (generic message;

        full detail is server-logged, not returned, to avoid leaking

        internals)


        ## Notes

        - User must have read permissions on the dataset

        - Events come only from the caller''s own sessions attributed to this

        dataset. Sessions carrying no dataset attribution are not included.

        - Attribution is per session, not per answered turn: a session id

        reused across datasets stays with the first dataset it touched, so

        its later turns appear on that dataset''s timeline.'
      operationId: visualize_live_events_api_v1_visualize_live_events_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: dataset_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: 'UUID of the dataset this poll is for. Gates who may call this endpoint (same read-permission check as every other visualize route) and scopes the events returned: only the caller''s own sessions attributed to this dataset contribute.'
          examples:
          - ''
          title: Dataset Id
        description: 'UUID of the dataset this poll is for. Gates who may call this endpoint (same read-permission check as every other visualize route) and scopes the events returned: only the caller''s own sessions attributed to this dataset contribute.'
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Cursor from a previous call's response. Omit on the first call to get every available event.
          title: Since
        description: Cursor from a previous call's response. Omit on the first call to get every available event.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/visualize/multi:
    post:
      tags:
      - visualize
      summary: Visualize Multi
      description: 'Generate a combined HTML visualization of graph data from multiple users'' datasets.


        This endpoint aggregates knowledge graphs from multiple user+dataset pairs

        into a single interactive visualization, with each user''s nodes tagged for

        color-by-user rendering.


        ## Request Body

        A JSON array of objects, each with:

        - **user_id** (UUID): The user who owns the dataset

        - **dataset_id** (UUID): The dataset to include


        ## Response

        Returns an HTML page containing the combined interactive graph visualization.


        ## Error Codes

        - **403 Forbidden**: Caller is not a superuser

        - **409 Conflict**: A user/dataset pair does not exist, is not readable,

        or visualization failed (detail in the `error` field)


        ## Notes

        - Requires superuser privileges to view other users'' data

        - Each user+dataset pair must exist and be accessible'
      operationId: visualize_multi_api_v1_visualize_multi_post
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/UserDatasetPair'
              type: array
              title: Pairs
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    UserDatasetPair:
      properties:
        user_id:
          type: string
          format: uuid
          title: User Id
          description: UUID of the user who owns the dataset (superuser-only endpoint; obtain via the permissions/users APIs).
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
          description: UUID of the dataset to include in the combined visualization (must be readable by user_id).
          examples:
          - 7c9e6679-7425-40de-944b-e07fc1f90ae7
      type: object
      required:
      - user_id
      - dataset_id
      title: UserDatasetPair
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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:
    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)