> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get knowledge graph

> Returns the full knowledge graph for the workspace, including CRM entity nodes, relationship edges, context edges (from ingested text), insight triplet edges (AI-extracted subject-predicate-object relationships), insight nodes, and insight link edges (semantic relationships between insights). Supports an optional `limit` query parameter to control the maximum number of entity nodes returned (default 1000, max 5000). Set `Accept: text/html` or `?format=html` to receive an interactive visualization.

<Note>
  This endpoint requires the `record.read` scope on your API key.
</Note>

## Overview

Returns the full knowledge graph for your workspace. The graph combines relationship data from your connected tools with AI-extracted knowledge from ingested context, providing a unified view of entities and their connections.

## Node Types

| Type              | ID Format     | Response Field  | Description                                                          |
| ----------------- | ------------- | --------------- | -------------------------------------------------------------------- |
| Entity            | `"12345"`     | `nodes`         | Resolved entities (people, companies, custom objects)                |
| Ghost             | `"ghost:123"` | `nodes`         | Entities mentioned in context but not yet resolved to a known entity |
| Entity insight    | `"ei:123"`    | `insight_nodes` | AI-extracted insight scoped to a specific entity                     |
| Knowledge insight | `"ki:123"`    | `insight_nodes` | Workspace-level AI-extracted knowledge                               |

## Edge Types

The `context_edges` array contains edges from multiple sources, distinguished by the `edge_type` field:

| Edge Type      | Description                                                                              | Has Confidence |
| -------------- | ---------------------------------------------------------------------------------------- | :------------: |
| `context`      | Relationships from ingested text (e.g., "involved\_in")                                  |       No       |
| `triplet`      | AI-extracted subject-predicate-object relationships (e.g., "works\_with", "reports\_to") |       Yes      |
| `insight`      | Links connecting insight nodes to entity nodes                                           |       No       |
| `insight_link` | Semantic relationships between insight nodes (`related_to` or `contradicts`)             |       Yes      |

### Insight Link Edges

`insight_link` edges represent semantic relationships discovered between insights. They connect two insight nodes (entity insights `ei:*` or knowledge insights `ki:*`) and always include a `confidence` score (0-1) representing semantic similarity.

**Labels:**

* `related_to` -- The two insights are semantically related
* `contradicts` -- The two insights contain contradictory information

```json theme={null}
{
  "id": "il_42",
  "source": "ei:100",
  "target": "ei:200",
  "label": "related_to",
  "edge_type": "insight_link",
  "confidence": 0.87
}
```

## Edge Priority

When both a `context` edge and a `triplet` edge exist between the same pair of nodes, generic context labels (`involved_in`, `context`) are suppressed in favor of the richer triplet edge. Non-generic context labels are kept alongside triplet edges.

## Interactive Visualization

Request HTML format to receive an interactive graph visualization:

```bash theme={null}
# Via query parameter
curl -s "https://app.nex.ai/api/developers/v1/graph?format=html" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Via Accept header
curl -s "https://app.nex.ai/api/developers/v1/graph" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/html"
```

## Example

```bash theme={null}
curl -s "https://app.nex.ai/api/developers/v1/graph?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "nodes": [
    {
      "id": "12345",
      "name": "John Smith",
      "type": "person",
      "definition_slug": "person",
      "primary_attribute": "John Smith",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "67890",
      "name": "Acme Corp",
      "type": "company",
      "definition_slug": "company",
      "primary_attribute": "Acme Corp",
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "edges": [
    {
      "id": "1001",
      "source": "12345",
      "target": "67890",
      "label": "works_at",
      "definition_id": "5"
    }
  ],
  "relationship_definitions": [
    {
      "id": "5",
      "name": "works_at",
      "entity_1_to_2": "works_at",
      "entity_2_to_1": "employs"
    }
  ],
  "context_edges": [
    {
      "id": "tri_42",
      "source": "12345",
      "target": "67890",
      "label": "leads_project_at",
      "edge_type": "triplet",
      "confidence": 0.92
    },
    {
      "id": "ei_edge_100",
      "source": "ei:100",
      "target": "12345",
      "label": "preference",
      "edge_type": "insight"
    },
    {
      "id": "il_7",
      "source": "ei:100",
      "target": "ei:200",
      "label": "related_to",
      "edge_type": "insight_link",
      "confidence": 0.87
    }
  ],
  "insight_nodes": [
    {
      "id": "ei:100",
      "content": "Prefers async communication over meetings",
      "type": "preference",
      "confidence": 0.85,
      "source": "entity_insight"
    },
    {
      "id": "ki:50",
      "content": "Q1 planning cycle typically starts in December",
      "type": "fact",
      "confidence": 0.90,
      "source": "knowledge_insight"
    }
  ],
  "insights": {
    "12345": [
      {
        "content": "Prefers async communication over meetings",
        "confidence": 0.85,
        "type": "preference"
      }
    ]
  },
  "total_nodes": 250,
  "total_edges": 180,
  "total_context_edges": 3
}
```


## OpenAPI

````yaml get /v1/graph
openapi: 3.0.0
info:
  description: >-
    REST API for accessing and managing your Nex data. Generate API keys from
    the Nex web UI and use them to authenticate requests.
  title: Nex Developer API
  contact: {}
  version: '1.0'
servers:
  - url: https://app.nex.ai/api/developers
security: []
paths:
  /v1/graph:
    get:
      tags:
        - Graph
      summary: Get knowledge graph
      description: >-
        Returns the full knowledge graph for the workspace, including CRM entity
        nodes, relationship edges, context edges (from ingested text), insight
        triplet edges (AI-extracted subject-predicate-object relationships),
        insight nodes, and insight link edges (semantic relationships between
        insights). Supports an optional `limit` query parameter to control the
        maximum number of entity nodes returned (default 1000, max 5000). Set
        `Accept: text/html` or `?format=html` to receive an interactive
        visualization.
      operationId: getGraph
      parameters:
        - description: Maximum number of entity nodes to return
          name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 1000
            maximum: 5000
            minimum: 1
        - description: >-
            Response format. Use `html` to receive an interactive graph
            visualization instead of JSON.
          name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - json
              - html
      responses:
        '200':
          description: Knowledge graph data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/graph.GraphResponse'
            text/html:
              schema:
                type: string
                description: Interactive HTML visualization of the knowledge graph
        '400':
          description: Bad request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    graph.GraphResponse:
      type: object
      description: Complete knowledge graph for the workspace
      properties:
        nodes:
          type: array
          description: >-
            CRM entity nodes (people, companies, custom objects) and ghost nodes
            (entities mentioned in context but not yet resolved to a CRM record)
          items:
            $ref: '#/components/schemas/graph.GraphNode'
        edges:
          type: array
          description: >-
            CRM relationship edges between entity nodes (e.g., person works_at
            company)
          items:
            $ref: '#/components/schemas/graph.GraphEdge'
        relationship_definitions:
          type: array
          description: Definitions of relationship types in the workspace
          items:
            $ref: '#/components/schemas/graph.GraphRelationshipDefinition'
        context_edges:
          type: array
          description: >-
            Edges derived from ingested context, AI-extracted triplets,
            insight-entity links, and insight-to-insight semantic relationships.
            Each edge has an `edge_type` indicating its source.
          items:
            $ref: '#/components/schemas/graph.ContextEdge'
        insight_nodes:
          type: array
          description: >-
            Insight nodes representing AI-extracted knowledge (entity insights
            and workspace-level knowledge insights)
          items:
            $ref: '#/components/schemas/graph.InsightNode'
        insights:
          type: object
          description: Per-entity insight summaries, keyed by entity ID
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/graph.EntityInsightSummary'
        total_nodes:
          type: integer
          description: >-
            Total number of entity nodes in the workspace (may exceed the
            returned count due to the limit parameter)
        total_edges:
          type: integer
          description: Total number of CRM relationship edges in the workspace
        total_context_edges:
          type: integer
          description: Total number of context edges returned (includes all edge types)
    httpx.APIError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    graph.GraphNode:
      type: object
      description: >-
        A node in the knowledge graph representing a CRM entity or a ghost
        (unresolved) entity
      properties:
        id:
          type: string
          description: >-
            Node ID. CRM entities use numeric IDs (e.g., "12345"). Ghost nodes
            use the format "ghost:<context_id>".
          example: '12345'
        name:
          type: string
          description: >-
            Display name (primary attribute value, or a generated name for
            unnamed entities)
          example: John Smith
        type:
          type: string
          description: Entity type name (e.g., "person", "company", "ghost")
          example: person
        definition_slug:
          type: string
          description: Slug of the entity definition
          example: person
        primary_attribute:
          type: string
          description: Value of the entity's primary attribute
        created_at:
          type: string
          format: date-time
          description: When the entity was created
    graph.GraphEdge:
      type: object
      description: A CRM relationship edge between two entity nodes
      properties:
        id:
          type: string
          description: Edge ID
        source:
          type: string
          description: Source node ID
        target:
          type: string
          description: Target node ID
        label:
          type: string
          description: Relationship label (e.g., "works_at", "reports_to")
          example: works_at
        definition_id:
          type: string
          description: ID of the relationship definition
    graph.GraphRelationshipDefinition:
      type: object
      description: Definition of a relationship type
      properties:
        id:
          type: string
          description: Definition ID
        name:
          type: string
          description: Display name
        entity_1_to_2:
          type: string
          description: Label from entity 1 to entity 2 (e.g., "works_at")
        entity_2_to_1:
          type: string
          description: Inverse label from entity 2 to entity 1 (e.g., "employs")
    graph.ContextEdge:
      type: object
      description: >-
        An edge in the context/knowledge layer of the graph. The `edge_type`
        field indicates the source: "context" (from ingested text), "triplet"
        (AI-extracted subject-predicate-object), "insight" (linking an insight
        node to an entity), or "insight_link" (semantic relationship between two
        insight nodes).
      properties:
        id:
          type: string
          description: >-
            Edge ID. Prefixed by type: "ctx_" for context, "tri_" for triplet,
            "ei_edge_" for entity insight edges, and "il_" for insight_link
            edges.
          example: tri_42
        source:
          type: string
          description: >-
            Source node ID. Can be an entity ID, ghost ID ("ghost:123"), or
            insight node ID ("ei:123" or "ki:123").
          example: '12345'
        target:
          type: string
          description: Target node ID
          example: '67890'
        label:
          type: string
          description: >-
            Edge label. For context edges: the relationship type. For triplets:
            the predicate (e.g., "works_with"). For insight edges: the insight
            type. For insight_link edges: "related_to" or "contradicts".
          example: works_with
        edge_type:
          type: string
          description: Source type of the edge
          enum:
            - context
            - triplet
            - insight
            - insight_link
        confidence:
          type: number
          format: double
          description: >-
            Confidence score (0-1). Present on triplet edges (extraction
            confidence) and insight_link edges (similarity score). Null/absent
            for context and insight edges.
          nullable: true
          minimum: 0
          maximum: 1
    graph.InsightNode:
      type: object
      description: An insight node representing AI-extracted knowledge
      properties:
        id:
          type: string
          description: >-
            Insight node ID. Entity insights use "ei:<id>", knowledge insights
            use "ki:<id>".
          example: ei:42
        content:
          type: string
          description: The insight text content
          example: John prefers email communication over phone calls
        type:
          type: string
          description: Insight type (e.g., "preference", "behavior", "fact")
          example: preference
        confidence:
          type: number
          format: double
          description: Confidence score (0-1)
          minimum: 0
          maximum: 1
        source:
          type: string
          description: >-
            Source type: "entity_insight" (scoped to an entity) or
            "knowledge_insight" (workspace-level)
          enum:
            - entity_insight
            - knowledge_insight
    graph.EntityInsightSummary:
      type: object
      description: Summary of an insight associated with a specific entity
      properties:
        content:
          type: string
          description: The insight text content
        confidence:
          type: number
          format: double
          description: Confidence score (0-1)
          minimum: 0
          maximum: 1
        type:
          type: string
          description: Insight type
  securitySchemes:
    ApiKeyAuth:
      description: 'API key for authentication (format: "Bearer YOUR_API_KEY")'
      type: apiKey
      name: Authorization
      in: header

````