---
title: Graph API
description: Knowledge graph entities and relationships endpoints
---

# Graph API

## Overview

Access the knowledge graph of entities (people, decisions, projects, technologies) and their relationships.

## GET /api/graph/entities

List all entities in the knowledge graph.

### Query Parameters

<TypeTable
  type={{
    channel_id: {
      type: 'string',
      description: 'Channel identifier',
      required: true,
    },
    type: {
      type: 'string',
      description: 'Filter by entity type',
    },
    status: {
      type: 'string',
      description: 'Filter by status (active, pending)',
    },
    limit: {
      type: 'int',
      description: 'Max results (max: 200)',
      default: '50',
    },
  }}
/>

### Entity Types

- `Person` - Team members, stakeholders
- `Decision` - Decisions made, conclusions
- `Project` - Projects, initiatives
- `Technology` - Tools, frameworks, libraries
- `Team` - Teams, groups
- `Meeting` - Meetings, standups

### Response

```json
[
  {
    "id": "entity_123",
    "name": "JWT Authentication",
    "type": "Decision",
    "scope": "channel",
    "channel_id": "C12345",
    "status": "active",
    "properties": {
      "decided_by": "Jane Smith",
      "date": "2026-04-13",
      "status": "implemented"
    },
    "aliases": ["JWT", "JWT Tokens"],
    "source_fact_ids": ["fact_456"],
    "created_at": "2026-04-13T10:30:00Z",
    "updated_at": "2026-04-13T10:30:00Z"
  }
]
```

## `GET /api/graph/entities/{entity_id}`

Get a specific entity by ID.

### Parameters

<TypeTable
  type={{
    entity_id: {
      type: 'string',
      description: 'Entity UUID',
      required: true,
    },
  }}
/>

### Response

```json
{
  "id": "entity_123",
  "name": "JWT Authentication",
  "type": "Decision",
  "scope": "channel",
  "channel_id": "C12345",
  "status": "active",
  "properties": {
    "decided_by": "Jane Smith",
    "date": "2026-04-13",
    "status": "implemented"
  },
  "aliases": ["JWT", "JWT Tokens"],
  "source_fact_ids": ["fact_456"],
  "source_message_id": "1234567890.123456",
  "message_ts": "2026-04-13T10:30:00Z",
  "created_at": "2026-04-13T10:30:00Z",
  "updated_at": "2026-04-13T10:30:00Z"
}
```

## `GET /api/graph/entities/{entity_id}/neighbors`

Get entities connected to a specific entity.

### Parameters

<TypeTable
  type={{
    entity_id: {
      type: 'string',
      description: 'Entity UUID',
      required: true,
    },
    depth: {
      type: 'int',
      description: 'Traversal depth (max: 3)',
      default: '1',
    },
    limit: {
      type: 'int',
      description: 'Max neighbors',
      default: '50',
    },
  }}
/>

### Response

```json
{
  "nodes": [
    {
      "id": "entity_123",
      "name": "JWT Authentication",
      "type": "Decision"
    },
    {
      "id": "entity_456",
      "name": "Jane Smith",
      "type": "Person"
    }
  ],
  "edges": [
    {
      "id": "rel_789",
      "type": "DECIDED_BY",
      "source": "JWT Authentication",
      "target": "Jane Smith",
      "confidence": 0.95,
      "context": "Jane decided to use JWT for authentication",
      "valid_from": "2026-04-13",
      "source_message_id": "1234567890.123456"
    }
  ]
}
```

## GET /api/graph/relationships

List all relationships in the knowledge graph.

### Query Parameters

<TypeTable
  type={{
    channel_id: {
      type: 'string',
      description: 'Channel identifier',
      required: true,
    },
    type: {
      type: 'string',
      description: 'Filter by relationship type',
    },
    source: {
      type: 'string',
      description: 'Filter by source entity name',
    },
    target: {
      type: 'string',
      description: 'Filter by target entity name',
    },
    limit: {
      type: 'int',
      description: 'Max results',
      default: '50',
    },
  }}
/>

### Relationship Types

- `DECIDED_BY` - Person → Decision
- `PARTICIPATED_IN` - Person → Meeting
- `WORKS_ON` - Person → Project
- `USES` - Project → Technology
- `MEMBER_OF` - Person → Team
- `RELATED_TO` - Generic relationship

### Response

```json
[
  {
    "id": "rel_789",
    "type": "DECIDED_BY",
    "source": "JWT Authentication",
    "target": "Jane Smith",
    "confidence": 0.95,
    "valid_from": "2026-04-13",
    "valid_until": null,
    "context": "Jane decided to use JWT for authentication",
    "source_message_id": "1234567890.123456",
    "source_fact_id": "fact_456",
    "created_at": "2026-04-13T10:30:00Z"
  }
]
```

## GET /api/graph/decisions

List all decisions with metadata.

### Parameters

<TypeTable
  type={{
    channel_id: {
      type: 'string',
      description: 'Channel identifier',
      required: true,
    },
    status: {
      type: 'string',
      description: 'Filter by status',
    },
  }}
/>

### Response

```json
[
  {
    "name": "JWT Authentication",
    "decided_by": "Jane Smith",
    "status": "implemented",
    "superseded_by": null,
    "date": "2026-04-13",
    "context": "Decision to use JWT tokens for API authentication"
  }
]
```

## `GET /api/graph/entities/{entity_name}/card`

Get an entity knowledge card (cross-channel aggregation).

### Parameters

<TypeTable
  type={{
    entity_name: {
      type: 'string',
      description: 'Entity name (URL-encoded)',
      required: true,
    },
  }}
/>

### Response

```json
{
  "id": "card_123",
  "tier": "entity_card",
  "entity_id": "entity_456",
  "entity_name": "JWT Authentication",
  "entity_type": "Decision",
  "channel_ids": ["C12345", "C67890"],
  "cluster_ids": ["topic_123"],
  "fact_count": 15,
  "fact_type_breakdown": {
    "decision": 8,
    "opinion": 4,
    "observation": 3
  },
  "key_facts": [
    "The team decided to use JWT tokens for authentication",
    "JWT expiration set to 1 hour"
  ],
  "related_entities": [
    {"name": "Jane Smith", "type": "Person", "relationship": "DECIDED_BY"},
    {"name": "OAuth", "type": "Technology", "relationship": "USES"}
  ],
  "last_mentioned_at": "2026-04-13T10:30:00Z",
  "staleness_score": 0.1,
  "summary": "Decision to implement JWT authentication for the API",
  "updated_at": "2026-04-13T10:30:00Z"
}
```

## GET /api/graph/entities/cards

List entity cards with filters.

### Query Parameters

<TypeTable
  type={{
    channel_id: {
      type: 'string',
      description: 'Filter by channel',
    },
    entity_type: {
      type: 'string',
      description: 'Filter by entity type',
    },
    limit: {
      type: 'int',
      description: 'Max results',
      default: '20',
    },
  }}
/>

### Response

```json
[
  {
    "entity_id": "entity_456",
    "entity_name": "JWT Authentication",
    "entity_type": "Decision",
    "fact_count": 15,
    "staleness_score": 0.1
  }
]
```

## Graph Queries

### Subgraph

Get a subgraph around entities:

```bash
GET /api/graph/subgraph?entities=JWT,Jane,Smith&depth=2
```

### Path Finding

Find paths between entities:

```bash
GET /api/graph/path?source=JWT&target=PostgreSQL&max_depth=3
```

### Common Neighbors

Find entities connected to multiple entities:

```bash
GET /api/graph/common-neighbors?entities=JWT,OAuth
```

## Entity Status

- **active**: Entity is active and referenced
- **pending**: Entity detected but awaiting confirmation

## Relationship Confidence

Relationships have a confidence score 0.0-1.0:

- **0.8-1.0**: High confidence (explicit statements)
- **0.5-0.8**: Medium confidence (strong implications)
- **0.0-0.5**: Low confidence (weak connections)
