Quickstart

Timepoint Clockchain is a PostgreSQL-backed temporal causal graph for AI agents. This guide will help you set up a local development instance and make your first API call.

Prerequisites

Before you begin, ensure you have:

Python 3.11+ installed on your system
PostgreSQL 16+ running locally or accessible via network
Git for cloning the repository
Basic familiarity with command-line tools

The Clockchain uses asyncpg for PostgreSQL connectivity and requires the pg_trgm extension for full-text search (optional but recommended).

Installation

Clone the repository

Clone the Clockchain repository to your local machine:

git clone https://github.com/timepoint-ai/timepoint-clockchain.git
cd timepoint-clockchain

Install dependencies

Install the package and its dependencies using pip or uv:

pip install -e ".[dev]"

This installs FastAPI, asyncpg, httpx, pydantic-settings, and the timepoint-tdf library.

Set up PostgreSQL

Create a database for the Clockchain. The schema will be created automatically on first startup.

# Start PostgreSQL service
brew services start postgresql@16

# Create the database
createdb clockchain

The Clockchain automatically creates the nodes and edges tables with appropriate indexes on startup. You don’t need to run any migration scripts.

Configure environment

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your configuration:

.env

# Required: PostgreSQL connection
DATABASE_URL=postgresql://localhost:5432/clockchain

# Required: Service authentication key
SERVICE_API_KEY=your-secret-key-here

# Required: Flash service configuration (optional for local dev)
FLASH_URL=http://localhost:8081
FLASH_SERVICE_KEY=your-flash-key-here

# Optional: Enable debug logging
DEBUG=true
ENVIRONMENT=development

# Optional: Autonomous graph expansion (requires OpenRouter)
EXPANSION_ENABLED=false
OPENROUTER_API_KEY=your-openrouter-key

# Optional: Daily "Today in History" worker
DAILY_CRON_ENABLED=false

The SERVICE_API_KEY is required for all protected API endpoints. Store it securely and never commit it to version control.

Running the Service

Start the Clockchain service using uvicorn:

uvicorn app.main:app --port 8080 --reload

You should see output similar to:

INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
INFO:     clockchain:Clockchain starting up (env=development)
INFO:     clockchain.db:Database pool created
INFO:     clockchain.db:Database schema initialized
INFO:     clockchain.db:Seeded 5 nodes and 3 edges
INFO:     Application startup complete.

On startup, the service:

Creates an asyncpg connection pool to PostgreSQL
Runs schema DDL to create nodes and edges tables
Seeds the database with 5 historical events from data/seeds.json (if empty)
Starts the GraphManager and FastAPI server

The initial seed data includes 5 historical moments: the Assassination of Julius Caesar (-44 BCE), the Trinity Test (1945), Apollo 11 Moon Landing (1969), Apollo 12 Lightning Launch (1969), and AlphaGo Move 37 (2016).

Making Your First API Call

Health Check

Verify the service is running:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "service": "timepoint-clockchain",
  "nodes": 5,
  "edges": 3
}

Browse the Graph

List available years in the graph:

curl -H "X-Service-Key: your-secret-key-here" \
  http://localhost:8080/api/v1/browse

Response:

{
  "segments": [
    {"segment": "-44", "type": "year", "count": 1},
    {"segment": "1945", "type": "year", "count": 1},
    {"segment": "1969", "type": "year", "count": 2},
    {"segment": "2016", "type": "year", "count": 1}
  ],
  "moments": []
}

Get a Moment

Retrieve a specific moment using its canonical URL path:

curl -H "X-Service-Key: your-secret-key-here" \
  http://localhost:8080/api/v1/moments/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing

Response:

{
  "id": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing",
  "name": "Apollo 11 Moon Landing",
  "year": 1969,
  "month": "july",
  "day": 20,
  "time": "2056",
  "country": "united-states",
  "region": "florida",
  "city": "cape-canaveral",
  "one_liner": "Neil Armstrong and Buzz Aldrin become the first humans to walk on the Moon",
  "tags": ["space", "nasa", "apollo-program", "moon"],
  "figures": ["Neil Armstrong", "Buzz Aldrin", "Michael Collins"],
  "visibility": "public",
  "layer": 1,
  "edges": [
    {
      "source": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing",
      "target": "/1969/november/14/1122/united-states/florida/cape-canaveral/apollo-12-lightning-launch",
      "edge_type": "contemporaneous",
      "weight": 0.9,
      "theme": "apollo-program"
    }
  ]
}

Search the Graph

Search for moments by name, tags, or figures:

curl -H "X-Service-Key: your-secret-key-here" \
  "http://localhost:8080/api/v1/search?q=apollo"

Response:

{
  "results": [
    {
      "id": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing",
      "name": "Apollo 11 Moon Landing",
      "one_liner": "Neil Armstrong and Buzz Aldrin become the first humans to walk on the Moon",
      "year": 1969,
      "tags": ["space", "nasa", "apollo-program", "moon"]
    },
    {
      "id": "/1969/november/14/1122/united-states/florida/cape-canaveral/apollo-12-lightning-launch",
      "name": "Apollo 12 Lightning Launch",
      "one_liner": "Apollo 12 launches into storm clouds and is struck by lightning twice",
      "year": 1969,
      "tags": ["space", "nasa", "apollo-program", "lightning"]
    }
  ]
}

Get Today’s Moments

Find all moments matching today’s month and day:

curl -H "X-Service-Key: your-secret-key-here" \
  http://localhost:8080/api/v1/today

This endpoint returns moments that match the current calendar date (month and day) from any year in history.

Understanding the Canonical URL Format

Every moment in the Clockchain has a unique spatiotemporal URL with 8 segments:

/year/month/day/time/country/region/city/slug

For example:

/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar
  │    │    │   │     │     │    │    └── event slug (auto-generated)
  │    │    │   │     │     │    └─────── city
  │    │    │   │     │     └──────────── region
  │    │    │   │     └───────────────── country (modern borders)
  │    │    │   └───────────────────────── time (24hr format, no colon)
  │    │    └───────────────────────────── day (1-31)
  │    └────────────────────────────────── month (lowercase name)
  └─────────────────────────────────────── year (negative = BCE)

Key characteristics:

Negative years represent BCE dates (e.g., -44 = 44 BCE)
Month names are lowercase (january, february, march, etc.)
Time is in 24-hour format without colons (0530 = 5:30 AM)
All segments use kebab-case (dashes instead of spaces)

Next Steps

API Reference

Explore the complete API documentation

Graph Architecture

Understand the underlying graph data model

TDF Integration

Export and ingest moments using the Timepoint Data Format

Autonomous Expansion

Enable LLM-driven graph growth with the Expander worker

Troubleshooting

Database Connection Errors

If you see connection refused errors, ensure PostgreSQL is running:

# Check PostgreSQL status (macOS)
brew services list

# Check PostgreSQL status (Linux)
sudo systemctl status postgresql

# Check Docker container
docker ps | grep clockchain-db

Authentication Failures

All protected endpoints require the X-Service-Key header. Verify your key matches the value in .env:

curl -H "X-Service-Key: your-secret-key-here" \
  http://localhost:8080/api/v1/browse

Empty Graph

If the graph is empty after startup, check that:

The data/seeds.json file exists in the repository root
The database tables were created successfully (check logs for schema errors)
The DATABASE_URL environment variable is set correctly

You can manually verify the database state:

psql clockchain -c "SELECT count(*) FROM nodes;"
psql clockchain -c "SELECT count(*) FROM edges;"

Get Started

Core Concepts

Autonomous Workers

Setup & Configuration

Integration

Prerequisites

Installation

Running the Service

Making Your First API Call

Health Check

Browse the Graph

Get a Moment

Search the Graph

Get Today’s Moments

Understanding the Canonical URL Format

Next Steps

API Reference

Graph Architecture

TDF Integration

Autonomous Expansion

Troubleshooting

Database Connection Errors

Authentication Failures

Empty Graph

Build docs developers (and LLMs) love

Get Started

Core Concepts

Autonomous Workers

Setup & Configuration

Integration

Documentation Index

​Prerequisites

​Installation

​Running the Service

​Making Your First API Call

​Health Check

​Browse the Graph

​Get a Moment

​Search the Graph

​Get Today’s Moments

​Understanding the Canonical URL Format

​Next Steps

API Reference

Graph Architecture

TDF Integration

Autonomous Expansion

​Troubleshooting

​Database Connection Errors

​Authentication Failures

​Empty Graph

Build docs developers (and LLMs) love

Prerequisites

Installation

Running the Service

Making Your First API Call

Health Check

Browse the Graph

Get a Moment

Search the Graph

Get Today’s Moments

Understanding the Canonical URL Format

Next Steps

Troubleshooting

Database Connection Errors

Authentication Failures

Empty Graph