Skip to main content

Knowledge Graph API

The Knowledge Graph API provides access to the knowledge graph visualization data. The knowledge graph represents entities (organizations, offerings, capabilities, competitors, etc.) and their relationships.

Get Knowledge Graph​

Fetch all knowledge graph nodes and edges for the workspace. Returns data in Cytoscape.js format for visualization.

GET /api/knowledge-graph

Response​

{
  "elements": {
    "nodes": [
      {
        "data": {
          "id": "node-id-1",
          "name": "My Company",
          "label": "ORGANIZATION",
          "color": "#3b82f6"
        }
      },
      {
        "data": {
          "id": "node-id-2",
          "name": "My Offering",
          "label": "OFFERING",
          "color": "#10b981"
        }
      }
    ],
    "edges": [
      {
        "data": {
          "id": "edge-id-1",
          "source": "node-id-1",
          "target": "node-id-2",
          "label": "HAS_OFFERING"
        }
      }
    ]
  }
}

Node Types​

Nodes can have the following types (labels):

  • ORGANIZATION - Your organization
  • OFFERING - Products/services
  • CAPABILITY - Capabilities/features
  • COMPETITOR - Competitor companies
  • PERSON - People/contacts
  • MARKET_EVENT - Market events
  • TOPIC - Topics/themes
  • DOCUMENT - Documents
  • DEAL - Win/loss deals
  • ARGUMENT - Reasons for win/loss

Edge Types​

Edges represent relationships:

  • HAS_OFFERING - Organization → Offering
  • IMPLEMENTS - Offering → Capability
  • COMPETES_WITH - Competitor → Competitor
  • RELATED_TO - Topic → Topic
  • HAS_DEAL - Organization → Deal
  • HAS_ARGUMENT - Deal → Argument
  • And more...

Get Nodes by IDs​

Fetch specific knowledge tree nodes by their IDs.

GET /api/nodes?ids={id1,id2,id3}&treeId={treeId}&excludeEmbeddings={true|false}

Query Parameters​

  • ids (string, required) - Comma-separated list of node IDs
  • treeId (string, required) - Tree ID (partition key)
  • excludeEmbeddings (boolean, optional) - Set to true to exclude embedding vectors from response (default: false)

Response​

{
  "nodes": [
    {
      "id": "node-id-1",
      "treeId": "tree-id",
      "text": "Node text content",
      "children": ["child-id-1", "child-id-2"],
      "metadata": {
        "source": "web",
        "url": "https://example.com"
      }
    }
  ]
}

Get Knowledge Tree​

Get a knowledge tree by tree ID.

GET /api/knowledge-trees/{treeId}

Path Parameters​

  • treeId (string, required) - Knowledge tree ID

Response​

{
  "tree": {
    "id": "tree-id",
    "treeId": "tree-id",
    "workspaceId": "workspace-id",
    "entityType": "COMPETITOR",
    "entityId": "competitor-id",
    "version": 1,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "sources": []
  }
}

Get Tree Nodes​

Get nodes for a specific knowledge tree.

GET /api/trees/{treeId}/nodes

Path Parameters​

  • treeId (string, required) - Knowledge tree ID

Query Parameters​

  • excludeEmbeddings (boolean, optional) - Set to true to exclude embedding vectors

Response​

{
  "nodes": [
    {
      "id": "node-id-1",
      "treeId": "tree-id",
      "text": "Node text content",
      "children": [],
      "metadata": {}
    }
  ]
}

Error Responses​

  • 400 - Bad Request (missing required parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 404 - Not Found (tree or node doesn't exist)

Use Cases​

  • Visualization: Use nodes and edges to build interactive graph visualizations
  • Exploration: Discover relationships between entities
  • Analysis: Understand competitive landscape through graph structure
  • Navigation: Traverse relationships between entities

Graph Structure​

The knowledge graph uses a Graph-on-NoSQL pattern:

  • Nodes: Represent entities (organizations, offerings, capabilities, etc.)
  • Edges: Represent relationships between entities
  • Properties: Additional metadata stored on nodes and edges
  • Types: Node and edge types define the ontology

Integration​

The knowledge graph is automatically updated when:

  • Competitors are added or refreshed
  • Offerings are created or updated
  • Deals are created
  • Intel items are collected
  • Capabilities are mapped

You can visualize the graph in the webapp or use this API to build custom visualizations.