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.

curl https://clockchain.timepointai.com/api/v1/stats

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

{
  "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

# 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:

{
  "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/

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

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 (traverse_moments, find_path).

GET /api/v1/graph/traverse/

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.

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:

{
  "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`)

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:

{
  "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 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:

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

Getting Started

Products

API Reference

Clockchain API

Clockchain API

Public Endpoints

GET /api/v1/stats

GET /api/v1/moments

GET /api/v1/moments/

Authenticated Endpoints

Graph Traversal

GET /api/v1/graph/traverse/

GET /api/v1/graph/path

MCP Endpoint

Interactive API Docs

TDF Export

​Clockchain API

​Public Endpoints

​GET /api/v1/stats

​GET /api/v1/moments

​GET /api/v1/moments/

​Authenticated Endpoints

​Graph Traversal

​GET /api/v1/graph/traverse/

​GET /api/v1/graph/path

​MCP Endpoint

​Interactive API Docs

​TDF Export

Clockchain API

Public Endpoints

GET /api/v1/stats

GET /api/v1/moments

GET /api/v1/moments/

Authenticated Endpoints

Graph Traversal

GET /api/v1/graph/traverse/

GET /api/v1/graph/path

MCP Endpoint

Interactive API Docs

TDF Export