Skip to main content

​
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: 
{
  "total_nodes": 1900,
  "total_edges": 5000000,
  "layer_counts": {"2": 1900},
  "edge_type_counts": {
    "causes": 73,
    "same_location": 42,
    "contemporaneous": 474,
    "thematic": 82
  },
  "source_type_counts": {"historical": 1900},
  "date_range": {"min_year": -700, "max_year": 2026},
  "avg_confidence": 0.85,
  "last_updated": "2026-03-10T00:00:00Z",
  "nodes_with_images": 561
}

​
GET /api/v1/moments

Paginated list of moments with filtering. Query Parameters:
ParameterTypeDescription
limitintMax results (default 20)
offsetintPagination offset
qstringFull-text search
year_fromintFilter: minimum year
year_tointFilter: maximum year
entitystringFilter by historical figure
sortstringSort 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": 1900,
  "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.
EndpointMethodAuthDescription
/browseGETX-Service-KeyBrowse graph with full metadata
/searchGETX-Service-KeySearch with advanced filters
/randomGETX-Service-KeyRandom moment
/todayGETX-Service-KeyToday in history
/generatePOSTWRITER_TOKENSGenerate new moment via Flash
/ingest/tdfPOSTWRITER_TOKENSIngest TDF record

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