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

# Clockchain API

> Query the temporal causal graph — public read access, no authentication required.

# Clockchain API

**Base URL:** `https://clockchain.timepointai.com`
**MCP Endpoint:** `https://clockchain.timepointai.com/mcp/` (Streamable HTTP, v1.26.0)

Public endpoints require no authentication. Write endpoints require `WRITER_TOKENS` (per-writer identity tokens). Admin endpoints require `X-Admin-Key`.

## Public Endpoints

### GET /api/v1/stats

Graph statistics.

```bash theme={null}
curl https://clockchain.timepointai.com/api/v1/stats
```

**Response** (illustrative snapshot — the graph grows continuously, so live totals will be larger):

```json theme={null}
{
  "total_nodes": 20396,
  "total_edges": 547616,
  "layer_counts": {"0": 8, "1": 18, "2": 20370},
  "edge_type_counts": {
    "causes": 864,
    "same_location": 47983,
    "contemporaneous": 47997,
    "thematic": 1991
  },
  "source_type_counts": {"historical": 20396},
  "date_range": {"min_year": -753, "max_year": 2086},
  "avg_confidence": 1.0,
  "last_updated": "2026-06-14T17:03:57Z",
  "nodes_with_images": 698
}
```

### GET /api/v1/moments

Paginated list of moments with filtering.

**Query Parameters:**

| Parameter   | Type   | Description                 |
| ----------- | ------ | --------------------------- |
| `limit`     | int    | Max results (default 20)    |
| `offset`    | int    | Pagination offset           |
| `q`         | string | Full-text search            |
| `year_from` | int    | Filter: minimum year        |
| `year_to`   | int    | Filter: maximum year        |
| `entity`    | string | Filter by historical figure |
| `sort`      | string | Sort order                  |

```bash theme={null}
# Search for events in Rome
curl "https://clockchain.timepointai.com/api/v1/moments?q=rome&limit=5"

# Events between 1900-2000
curl "https://clockchain.timepointai.com/api/v1/moments?year_from=1900&year_to=2000"
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "path": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing",
      "event_name": "Apollo 11 Moon Landing",
      "year": 1969,
      "layer": 2,
      "figures": ["Neil Armstrong", "Buzz Aldrin"],
      "tags": ["space", "nasa", "cold-war"],
      "image_url": "https://cdn.timepointai.com/scenes/apollo-11-moon-landing.jpg"
    }
  ],
  "total": 20396,
  "limit": 5,
  "offset": 0
}
```

### GET /api/v1/moments/{path}

Get a specific moment by canonical path, including its edges.

```bash theme={null}
curl "https://clockchain.timepointai.com/api/v1/moments/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar"
```

## Authenticated Endpoints

Write endpoints require a valid writer token (from `WRITER_TOKENS`). Admin endpoints require `X-Admin-Key`.

| Endpoint                        | Method | Auth            | Description                                      |
| ------------------------------- | ------ | --------------- | ------------------------------------------------ |
| `/browse`                       | GET    | `X-Service-Key` | Browse graph with full metadata                  |
| `/search`                       | GET    | `X-Service-Key` | Search with advanced filters                     |
| `/random`                       | GET    | `X-Service-Key` | Random moment                                    |
| `/today`                        | GET    | `X-Service-Key` | Today in history                                 |
| `/api/v1/graph/traverse/{path}` | GET    | `X-Service-Key` | Multi-hop causal traversal from an anchor moment |
| `/api/v1/graph/path`            | GET    | `X-Service-Key` | Shortest path between two moments                |
| `/generate`                     | POST   | `WRITER_TOKENS` | Generate new moment via Flash                    |
| `/ingest/tdf`                   | POST   | `WRITER_TOKENS` | Ingest TDF record                                |

## Graph Traversal

Two endpoints power multi-hop navigation of the causal graph. Both require `X-Service-Key`. Agents without a service key can use the equivalent free [MCP tools](/api-reference/mcp) (`traverse_moments`, `find_path`).

### GET /api/v1/graph/traverse/{path}

Breadth-first subgraph expansion from an anchor moment — walk N hops into a moment's causes and consequences.

**Query Parameters:**

| Parameter    | Type   | Description                                                                       |
| ------------ | ------ | --------------------------------------------------------------------------------- |
| `direction`  | string | `past`, `future`, or `both` (default `both`)                                      |
| `depth`      | int    | Hops from the anchor, 1–4 (default 2)                                             |
| `edge_types` | string | CSV subset of edge types (default `causes,caused_by,precedes,follows,influences`) |
| `limit`      | int    | Max nodes returned (default 100, hard cap 500)                                    |
| `min_weight` | float  | Minimum edge weight (default 0.0)                                                 |

**Direction semantics** (edges are stored source → target):

| Direction | Traverses                                                                        |
| --------- | -------------------------------------------------------------------------------- |
| `future`  | Out-edges of `causes`/`precedes`/`influences`; in-edges of `caused_by`/`follows` |
| `past`    | Out-edges of `caused_by`/`follows`; in-edges of `causes`/`precedes`/`influences` |
| `both`    | Union of the two                                                                 |

Symmetric types (`contemporaneous`, `same_era`, `same_location`, `same_conflict`, `same_figure`, `thematic`, `challenges`) traverse in both directions and are only included when explicitly listed in `edge_types`.

```bash theme={null}
curl "https://clockchain.timepointai.com/api/v1/graph/traverse/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar?direction=future&depth=2&limit=50" \
  -H "X-Service-Key: YOUR_KEY"
```

**Response:**

```json theme={null}
{
  "anchor": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
  "direction": "future",
  "depth": 2,
  "nodes": [
    {
      "id": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
      "name": "Assassination of Julius Caesar",
      "year": -44,
      "month_num": 3,
      "day": 15,
      "era": "classical",
      "type": "historical",
      "layer": 2,
      "country": "italy",
      "region": "lazio",
      "city": "rome",
      "latitude": 41.8919,
      "longitude": 12.5113,
      "confidence": 1.0,
      "status": "active",
      "hop": 0
    }
  ],
  "edges": [
    {
      "source": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
      "target": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed",
      "type": "causes",
      "weight": 0.9,
      "theme": "power-vacuum",
      "description": "Caesar's death triggered the power struggle that produced the Second Triumvirate."
    }
  ],
  "node_count": 12,
  "edge_count": 17,
  "truncated": false
}
```

The anchor node is always included with `hop: 0`; each other node carries the hop level at which BFS first reached it. `truncated` is `true` when `limit` clipped the expansion. Returns `404` if the anchor moment doesn't exist.

### GET /api/v1/graph/path

Shortest connection between two moments — bidirectional BFS treating edges as undirected for connectivity.

**Query Parameters:**

| Parameter    | Type   | Description                                                       |
| ------------ | ------ | ----------------------------------------------------------------- |
| `from`       | string | Canonical path of the start moment                                |
| `to`         | string | Canonical path of the end moment                                  |
| `max_hops`   | int    | Search bound, default 6, cap 10                                   |
| `edge_types` | string | CSV subset of edge types (default: all types except `challenges`) |

```bash theme={null}
curl -G "https://clockchain.timepointai.com/api/v1/graph/path" \
  -H "X-Service-Key: YOUR_KEY" \
  --data-urlencode "from=/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar" \
  --data-urlencode "to=/-31/september/2/1400/greece/epirus/actium/battle-of-actium" \
  --data-urlencode "max_hops=6"
```

**Response:**

```json theme={null}
{
  "found": true,
  "from": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
  "to": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium",
  "hops": 2,
  "nodes": [
    {"id": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "name": "Assassination of Julius Caesar", "hop": 0},
    {"id": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "name": "Second Triumvirate Formed", "hop": 1},
    {"id": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium", "name": "Battle of Actium", "hop": 2}
  ],
  "edges": [
    {"source": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "target": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "type": "causes", "weight": 0.9},
    {"source": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "target": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium", "type": "precedes", "weight": 0.7}
  ]
}
```

Nodes and edges are ordered along the path (`hop` = position). When no path exists within `max_hops`, the response is `200` with `"found": false` — `404` is returned only when either endpoint moment doesn't exist. Node objects use the same shape as `traverse` (abbreviated above).

## MCP Endpoint

The Clockchain exposes its temporal causal graph via the **Model Context Protocol (MCP)** at:

```
https://clockchain.timepointai.com/mcp/
```

Transport: **Streamable HTTP** (v1.26.0). See the [MCP documentation](/api-reference/mcp) for tools and integration details.

## Interactive API Docs

The Clockchain provides built-in interactive documentation:

* **Swagger UI:** `/docs` — try endpoints directly in the browser
* **ReDoc:** `/redoc` — readable reference documentation

### TDF Export

Add `?format=tdf` to any moment endpoint to get TDF-formatted output:

```bash theme={null}
curl "https://clockchain.timepointai.com/api/v1/moments/{path}?format=tdf" \
  -H "X-Service-Key: YOUR_KEY"
```