Index Moment

Overview

The /index endpoint allows you to manually create moment nodes in the Clockchain graph without using the Flash Timepoint API. This is useful for:

Importing pre-structured historical data
Creating custom moments from external sources
Indexing moments that already have Flash Timepoint IDs
Bulk imports from structured datasets
Integration with third-party historical databases

Unlike the Generate endpoint, /index does not call the Flash API. You must provide all moment metadata manually.

Authentication

Requires SERVICE_API_KEY header for authentication.

X-Service-Key: your-service-api-key

Request Body

path

string

required

The full graph path where the moment should be indexed.Format: /YYYY/month/DD/HHMM/country/region/city/event-slugExample: /1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-moon-landing

metadata

object

default:"{}"

Additional node attributes to store with the moment. Common fields:

name (string) - Event name/title
one_liner (string) - Brief description
year (integer) - Year of event
month (string) - Month name
month_num (integer) - Month number (1-12)
day (integer) - Day of month
time (string) - Time in HHMM format
country (string) - Country slug
region (string) - Region slug
city (string) - City slug
tags (array) - Tag strings
figures (array) - Names of key figures
slug (string) - URL-friendly identifier
era (string) - Historical era
Any custom fields your application needs

flash_timepoint_id

string

If this moment was generated by Flash Timepoint API externally, provide the Flash ID to link it.When provided, the node’s layer is automatically set to at least 2 (Flash-generated content layer).

visibility

string

default:"private"

Visibility level for the indexed moment.Options:

private - Only visible to authorized users
public - Visible to all users
unlisted - Accessible via direct link

created_by

string

default:"system"

Identifier for who/what created this moment. Can be a user ID, system name, or data source identifier.

Response

path

string

The graph path where the moment was indexed.

status

string

Will always be indexed on success.

Example Request (Basic)

curl -X POST https://api.clockchain.io/api/index \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-api-key" \
  -d '{
    "path": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-landing",
    "metadata": {
      "name": "Apollo 11 Moon Landing",
      "one_liner": "First humans land on the Moon",
      "year": 1969,
      "month": "july",
      "month_num": 7,
      "day": 20,
      "time": "2056",
      "country": "united-states",
      "region": "florida",
      "city": "cape-canaveral",
      "tags": ["space", "nasa", "moon", "apollo"],
      "figures": ["Neil Armstrong", "Buzz Aldrin", "Michael Collins"]
    },
    "visibility": "public",
    "created_by": "data-import-script"
  }'

Example Response

{
  "path": "/1969/july/20/2056/united-states/florida/cape-canaveral/apollo-11-landing",
  "status": "indexed"
}

Example Request (With Flash ID)

curl -X POST https://api.clockchain.io/api/index \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-api-key" \
  -d '{
    "path": "/1776/july/04/1200/united-states/pennsylvania/philadelphia/declaration-independence",
    "flash_timepoint_id": "tp_a3d8f7e2_4c1b_4a9e",
    "metadata": {
      "name": "Signing of the Declaration of Independence",
      "one_liner": "Continental Congress adopts Declaration of Independence",
      "year": 1776,
      "tags": ["american-revolution", "independence", "founding-documents"],
      "figures": ["Thomas Jefferson", "John Adams", "Benjamin Franklin"]
    },
    "visibility": "public",
    "created_by": "flash-integration"
  }'

Node Attributes

The indexed node will have the following attributes:

Automatic Attributes

type - Always set to "event"
layer - Set to 0 by default, or 2 minimum if flash_timepoint_id is provided
created_at - Automatically set to current UTC timestamp

Required via Metadata

name - Event name
year, month, day, time - Temporal data
country, region, city - Spatial data

Optional Metadata

one_liner - Brief description
tags - Categorization tags
figures - Key historical figures involved
era - Historical period/era
slug - URL identifier
flash_slug - Flash Timepoint slug if applicable
flash_share_url - Flash Timepoint share URL
source_type - Data source classification
confidence - Confidence score (0.0-1.0)
Custom fields as needed

Layer System

Graph Layers represent data quality/origin:

Layer 0: Manually indexed, unverified data
Layer 1: Algorithmically derived connections
Layer 2+: Flash API generated, high-quality content

When flash_timepoint_id is provided, layer is automatically set to at least 2.

Use Cases

Import from Structured Dataset

# Import from CSV/JSON with pre-computed paths
curl -X POST https://api.clockchain.io/api/index \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-api-key" \
  -d '{
    "path": "/1865/april/14/2215/united-states/washington-dc/fords-theatre/lincoln-assassination",
    "metadata": {
      "name": "Assassination of Abraham Lincoln",
      "year": 1865,
      "tags": ["civil-war", "assassination", "lincoln"],
      "figures": ["Abraham Lincoln", "John Wilkes Booth"],
      "source_type": "historical_database"
    },
    "visibility": "public",
    "created_by": "wikipedia-import-bot"
  }'

Link External Flash Timepoints

# Index a moment generated externally via Flash API
curl -X POST https://api.clockchain.io/api/index \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-api-key" \
  -d '{
    "path": "/1945/august/06/0815/japan/chugoku/hiroshima/atomic-bombing",
    "flash_timepoint_id": "tp_external_12345",
    "metadata": {
      "name": "Atomic Bombing of Hiroshima",
      "flash_share_url": "https://flash.timepoint.ai/moments/tp_external_12345",
      "tags": ["wwii", "nuclear", "japan"]
    },
    "visibility": "public"
  }'

Create Custom Event Types

# Index non-Flash content with custom attributes
curl -X POST https://api.clockchain.io/api/index \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-api-key" \
  -d '{
    "path": "/2024/january/15/1430/united-states/california/palo-alto/company-founding",
    "metadata": {
      "name": "Acme Corp Founded",
      "custom_field_1": "corporate_event",
      "custom_field_2": 1000000,
      "tags": ["business", "startup"]
    },
    "visibility": "private",
    "created_by": "internal-timeline-system"
  }'

Path Format Requirements

Path Validation: The path must follow the standard Clockchain format:/YYYY/month-name/DD/HHMM/country/region/city/event-slug

Year: 4-digit year (negative for BCE)
Month: Lowercase month name (january, february, etc.)
Day: 2-digit day (01-31)
Time: 4-digit HHMM format (0000-2359)
Location: Lowercase, hyphenated slugs
Slug: Lowercase, hyphenated event identifier

Error Responses

Status Code	Description
400	Missing required `path` field
401	Missing or invalid SERVICE_API_KEY
409	Node already exists at the specified path
500	Graph indexing error

Comparison with Generate

Feature	`/index`	`/generate`
Flash API call	No	Yes
Job processing	Immediate	Async background
Requires metadata	Yes, manual	No, auto-extracted
Use case	Structured imports	Natural language queries
Cost	No Flash API cost	Flash API credits
Response time	~100ms	5-30 seconds

Generate - AI-powered moment generation
Bulk Generate - Batch AI generation
Expand Once - Graph expansion
/api/moments/{path} - Retrieve indexed moments

Overview

Moments

Graph

Generation

Ingestion

Overview

Authentication

Request Body

Response

Example Request (Basic)

Example Response

Example Request (With Flash ID)

Node Attributes

Automatic Attributes

Required via Metadata

Optional Metadata

Layer System

Use Cases

Import from Structured Dataset

Link External Flash Timepoints

Create Custom Event Types

Path Format Requirements

Error Responses

Comparison with Generate

Build docs developers (and LLMs) love

Overview

Moments

Graph

Generation

Ingestion

Documentation Index

​Overview

​Authentication

​Request Body

​Response

​Example Request (Basic)

​Example Response

​Example Request (With Flash ID)

​Node Attributes

​Automatic Attributes

​Required via Metadata

​Optional Metadata

​Layer System

​Use Cases

​Import from Structured Dataset

​Link External Flash Timepoints

​Create Custom Event Types

​Path Format Requirements

​Error Responses

​Comparison with Generate

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Authentication

Request Body

Response

Example Request (Basic)

Example Response

Example Request (With Flash ID)

Node Attributes

Automatic Attributes

Required via Metadata

Optional Metadata

Layer System

Use Cases

Import from Structured Dataset

Link External Flash Timepoints

Create Custom Event Types

Path Format Requirements

Error Responses

Comparison with Generate

Related Endpoints