Documentation Index
Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt
Use this file to discover all available pages before exploring further.
Every node in the Clockchain has a unique canonical URL that encodes both when and where the event occurred. This 8-segment path serves as the node’s primary key and its API address.
The canonical URL consists of 8 segments in a fixed order:
/{year}/{month}/{day}/{time}/{country}/{region}/{city}/{slug}
Example: Assassination of Julius Caesar
/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar
│ │ │ │ │ │ │ └── slug (auto-generated)
│ │ │ │ │ │ └─────── city
│ │ │ │ │ └──────────── region
│ │ │ │ └───────────────── country (modern borders)
│ │ │ └───────────────────── time (24hr, no colon)
│ │ └───────────────────────── day
│ └────────────────────────────── month (lowercase name)
└─────────────────────────────────── year (negative = BCE)
Negative years represent BCE dates. For example, -44 is 44 BCE.
Segment Definitions
| Segment | Type | Description | Example |
|---|
year | Integer | Negative for BCE, positive for CE | -44, 1969, 2016 |
month | String | Lowercase month name | march, july, november |
day | Integer | Day of month (1-31) | 15, 20 |
time | String | 24-hour time without colon | 1030, 1456, 0900 |
country | String | Modern country name (kebab-case) | italy, united-states |
region | String | State/province/region (kebab-case) | lazio, texas, new-mexico |
city | String | City name (kebab-case) | rome, houston, los-alamos |
slug | String | Auto-generated event identifier | assassination-of-julius-caesar |
All text segments use kebab-case (lowercase with hyphens). Unicode characters are normalized to ASCII.
Slug Generation
Slugs are automatically generated from event names using the slugify() function:
# From url.py:24-29
def slugify(text: str) -> str:
text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
text = text.lower().strip()
text = re.sub(r"[^\w\s-]", "", text)
text = re.sub(r"[-\s]+", "-", text)
return text.strip("-")
| Input | Slug |
|---|
"Assassination of Julius Caesar" | assassination-of-julius-caesar |
"Apollo 11: Moon Landing" | apollo-11-moon-landing |
"AlphaGo — Move 37" | alphago-move-37 |
Building Canonical Paths
The build_path() function constructs a canonical URL from components:
# From url.py:32-47
def build_path(
year: int,
month: int,
day: int,
time: str,
country: str,
region: str,
city: str,
slug: str,
) -> str:
month_name = NUM_TO_MONTH.get(month, "")
country_slug = slugify(country)
region_slug = slugify(region)
city_slug = slugify(city)
slug_clean = slugify(slug) if slug else ""
return f"/{year}/{month_name}/{day}/{time}/{country_slug}/{region_slug}/{city_slug}/{slug_clean}"
Usage Example
from app.core.url import build_path
path = build_path(
year=-44,
month=3, # March
day=15,
time="1030",
country="Italy",
region="Lazio",
city="Rome",
slug="Assassination of Julius Caesar"
)
# Result: "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar"
Parsing Canonical Paths
The parse_path() function extracts components from a canonical URL:
# From url.py:50-79
def parse_path(path: str) -> dict | None:
path = path.strip("/")
parts = path.split("/")
if len(parts) != 8:
return None
try:
year = int(parts[0])
month_str = parts[1].lower()
month = MONTH_TO_NUM.get(month_str)
if month is None:
return None
day = int(parts[2])
time_str = parts[3]
country = parts[4]
region = parts[5]
city = parts[6]
slug = parts[7]
return {
"year": year,
"month": month,
"month_name": month_str,
"day": day,
"time": time_str,
"country": country,
"region": region,
"city": city,
"slug": slug,
}
except (ValueError, IndexError):
return None
Parsing Example
from app.core.url import parse_path
result = parse_path("/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar")
# Returns:
# {
# "year": -44,
# "month": 3,
# "month_name": "march",
# "day": 15,
# "time": "1030",
# "country": "italy",
# "region": "lazio",
# "city": "rome",
# "slug": "assassination-of-julius-caesar"
# }
If a path doesn’t have exactly 8 segments, parse_path() returns None. Use parse_partial_path() for hierarchical browsing.
Partial Path Parsing
For hierarchical browsing (e.g., /1969/july), use parse_partial_path():
# From url.py:82-109
def parse_partial_path(path: str) -> dict[str, int | str]:
path = path.strip("/")
if not path:
return {}
parts = path.split("/")
result: dict[str, int | str] = {}
for i, segment in enumerate(parts):
if i >= len(PATH_SEGMENTS):
break
key = PATH_SEGMENTS[i]
if key == "year":
try:
result[key] = int(segment)
except ValueError:
result[key] = segment
elif key == "month":
result[key] = segment.lower()
m = MONTH_TO_NUM.get(segment.lower())
if m is not None:
result["month_num"] = m
elif key == "day":
try:
result[key] = int(segment)
except ValueError:
result[key] = segment
else:
result[key] = segment
return result
Partial Parsing Example
from app.core.url import parse_partial_path
result = parse_partial_path("/1969/july")
# Returns:
# {
# "year": 1969,
# "month": "july",
# "month_num": 7
# }
Month Name Mappings
The URL system maintains bidirectional month mappings:
# From url.py:4-19
MONTHS = [
"january", "february", "march", "april", "may", "june",
"july", "august", "september", "october", "november", "december"
]
MONTH_TO_NUM = {m: i + 1 for i, m in enumerate(MONTHS)}
NUM_TO_MONTH = {i + 1: m for i, m in enumerate(MONTHS)}
| Number | Name |
|---|
| 1 | january |
| 2 | february |
| 3 | march |
| … | … |
| 12 | december |
Real-World Examples
Trinity Test (1945)
/1945/july/16/0529/united-states/new-mexico/los-alamos/trinity-test
Apollo 11 Moon Landing (1969)
/1969/july/20/2017/united-states/florida/cape-canaveral/apollo-11-moon-landing
AlphaGo Move 37 (2016)
/2016/march/13/1637/south-korea/seoul/seoul/alphago-move-37
Canonical URLs are used directly as the id field in the nodes table and as the path parameter in API routes like /api/v1/moments/{path}.
API Integration
Canonical URLs serve as both database primary keys and API route parameters:
# Fetch a specific moment
GET /api/v1/moments/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar
# Get neighbors of a moment
GET /api/v1/graph/neighbors/1969/july/20/2017/united-states/florida/cape-canaveral/apollo-11-moon-landing
# Publish a moment
POST /api/v1/moments/1945/july/16/0529/united-states/new-mexico/los-alamos/trinity-test/publish