Skip to main content

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.

​
Overview

The /ingest/tdf endpoint accepts a batch of TDF-compliant records and creates or updates nodes in the Clockchain graph. Each record is automatically deduplicated using a deterministic tdf_hash computed from canonical temporal-spatial fields.

​
Endpoint

​
POST
string
/api/v1/ingest/tdf

​
Authentication

Requires a valid service key passed via the X-Service-Key header. 
curl -X POST https://api.timepoint.io/api/v1/ingest/tdf \
  -H "X-Service-Key: your-service-key" \
  -H "Content-Type: application/json"

​
Request Body

​
records
array
required
Array of TDF record objects. Each record represents a single timepoint node.

​
TDF Record Structure

Each record in the array follows the Temporal Data Format specification:

​
Response

​
ingested_nodes
integer
Number of nodes successfully ingested.

​
Example Request

curl -X POST https://api.timepoint.io/api/v1/ingest/tdf \
  -H "X-Service-Key: your-service-key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "1969/07/moon-landing",
      "source": "clockchain",
      "timestamp": "2024-03-15T10:30:00Z",
      "provenance": {
        "generator": "historical-import-v2",
        "confidence": 0.98,
        "run_id": "batch-2024-03-15"
      },
      "payload": {
        "year": 1969,
        "month": "July",
        "month_num": 7,
        "day": 20,
        "time": "20:17",
        "country": "United States",
        "region": "Space",
        "city": "Moon",
        "slug": "moon-landing",
        "name": "Apollo 11 Moon Landing",
        "one_liner": "First humans land on the Moon",
        "layer": 0,
        "visibility": "public",
        "tags": ["space", "nasa", "exploration"],
        "figures": ["Neil Armstrong", "Buzz Aldrin"],
        "source_type": "historical"
      }
    }
  ]'

​
Example Response

{
  "ingested_nodes": 1
}

​
Deduplication with tdf_hash

Each TDF record generates a deterministic SHA-256 hash from its canonical fields. This tdf_hash is used for content-addressable deduplication.
The tdf_hash is computed from the following fields in the payload:
  • year, month, day, time
  • country, region, city
  • slug, name, one_liner
The hash is stable across ingestions:
  • Missing or null values are normalized to empty strings
  • All values are lowercased and trimmed
  • Fields are sorted alphabetically before hashing
Behavior:
  • If a node with the same id and tdf_hash already exists, it is not duplicated
  • If the tdf_hash differs (content changed), the node is updated
  • This enables idempotent bulk imports and change detection

​
Processing Flow

  1. Validation: Each record is validated against the TDFRecord schema
  2. Transformation: The tdf_to_node_attrs() function extracts node attributes
  3. Hash Computation: The tdf_hash is automatically computed from canonical fields
  4. Ingestion: The node is added or updated via GraphManager.add_node()
  5. Response: Returns the total count of processed nodes

​
Error Handling

  • 400 Bad Request: Invalid TDF record structure or missing required fields
  • 401 Unauthorized: Missing or invalid service key
  • 422 Unprocessable Entity: TDF schema validation failed

​
Best Practices

  • Batch Size: Optimal batch size is 100-1000 records per request
  • Idempotency: Safe to retry failed batches—duplicates are handled automatically
  • Confidence Scores: Use confidence values to track data quality (0.0 = uncertain, 1.0 = verified)
  • Run IDs: Use consistent run_id values to track ingestion batches
  • Source Types: Tag records with source_type to distinguish historical facts from generated or user content

Build docs developers (and LLMs) love

Get started for freeTalk to us