Ingest Subgraph

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

​

Endpoint

​

Authentication

curl -X POST https://api.timepoint.io/api/v1/ingest/subgraph \
  -H "X-Service-Key: your-service-key" \
  -H "Content-Type: application/json"

​

Request Body

​

Node Structure

​

Edge Structure

​

Response

​

Example Request

curl -X POST https://api.timepoint.io/api/v1/ingest/subgraph \
  -H "X-Service-Key: your-service-key" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "1957/10/sputnik-1",
        "name": "Sputnik 1 Launch",
        "year": 1957,
        "month": "October",
        "month_num": 10,
        "day": 4,
        "country": "Soviet Union",
        "slug": "sputnik-1",
        "one_liner": "First artificial satellite in orbit",
        "layer": 0,
        "visibility": "public",
        "tags": ["space", "satellite", "cold-war"],
        "figures": ["Sergei Korolev"],
        "source_type": "historical",
        "confidence": 1.0,
        "source_run_id": "space-race-import"
      },
      {
        "id": "1969/07/moon-landing",
        "name": "Apollo 11 Moon Landing",
        "year": 1969,
        "month": "July",
        "month_num": 7,
        "day": 20,
        "time": "20:17",
        "country": "United States",
        "region": "Space",
        "city": "Moon",
        "slug": "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",
        "confidence": 1.0,
        "source_run_id": "space-race-import"
      }
    ],
    "edges": [
      {
        "source": "1957/10/sputnik-1",
        "target": "1969/07/moon-landing",
        "type": "causal",
        "weight": 0.85,
        "theme": "space-race"
      }
    ]
  }'

​

Example Response

{
  "ingested_nodes": 2,
  "ingested_edges": 1
}

​

Deduplication Behavior

1. If you provide a tdf_hash in the request, it will be used as-is
2. If omitted, the system computes the hash from these fields:
   • Temporal: year, month, day, time
   • Spatial: country, region, city
   • Content: slug, name, one_liner
3. Nodes with matching id and tdf_hash are considered duplicates and won’t create new entries
4. If the content changes (different hash), the node is updated

• Edges are identified by (source, target, type) tuple
• Duplicate edges are silently ignored
• Invalid edge types are skipped (logged but don’t fail the request)

​

Source Types and Confidence

​

Source Type

{
  "source_type": "historical",
  "confidence": 1.0
}

• historical: Verified historical facts from reliable sources
• generated: AI-generated content (may require fact-checking)
• user_input: User-submitted events
• synthetic: Programmatically created for testing or simulation

​

Confidence Scoring

• 1.0: Fully verified, primary source
• 0.8-0.9: High confidence, secondary sources
• 0.5-0.7: Medium confidence, needs verification
• 0.0-0.4: Low confidence, speculative or uncertain

​

Edge Types

​

Error Handling

• Invalid edge types are skipped (not an error)
• Both source and target nodes must exist before creating an edge
• If an edge references non-existent nodes, it’s silently ignored

​

Best Practices

​

Batch Size

• Optimal: 50-500 nodes with 100-1000 edges per request
• Large subgraphs: Split into multiple requests grouped by temporal or thematic clusters

​

Node and Edge Ordering

• Include all nodes before their edges (nodes are processed first anyway)
• Edges referencing non-existent nodes will be skipped

​

Provenance Tracking

• Use consistent source_run_id values for each import batch
• Tag generated content with confidence < 1.0
• Set appropriate source_type for downstream filtering

​

Idempotency

• Safe to retry failed requests
• Duplicate nodes/edges are automatically handled
• Use the same tdf_hash values for consistent deduplication

​

Use Cases

{
  "nodes": [/* causally-linked events */],
  "edges": [{"type": "causal", "weight": 0.9}]
}

{
  "nodes": [/* related events */],
  "edges": [{"type": "thematic", "theme": "industrial-revolution"}]
}

{
  "nodes": [/* events in same location */],
  "edges": [{"type": "spatial", "weight": 1.0}]
}

​

Related Endpoints

• Ingest TDF Records - Bulk import nodes without explicit edges
• Get Moment - Retrieve a node with its edges
• Graph Stats - View ingestion statistics by source type