How to Get a Point-in-Time Snapshot of the Semantica Graph: 4 Methods Explained

Retrieve a point-in-time snapshot of the Semantica graph by calling the GET /api/temporal/snapshot endpoint with an optional at ISO-8601 timestamp parameter, or use the built-in CLI skill semantica:temporal snapshot.

The semantica-agi/semantica repository implements a bi-temporal knowledge graph that maintains complete historical state, allowing you to query the graph as it existed at any previous moment. This guide demonstrates how to extract a point-in-time snapshot of the Semantica graph using the platform's HTTP API, frontend components, and command-line tools.

Understanding the Temporal Snapshot Endpoint

Semantica exposes a dedicated HTTP endpoint for retrieving historical graph states. The GET /api/temporal/snapshot endpoint accepts an optional at query parameter containing an ISO-8601 timestamp. When omitted, the endpoint returns the current state. When provided, it reconstructs the graph exactly as it existed at that specific moment.

According to the API documentation in docs/reference/explorer.md, the endpoint returns a JSON payload containing the complete set of nodes, edges, and metadata for the requested temporal state. The test suite in tests/explorer/test_explorer_api.py (lines 518-531) validates this behavior across multiple historic timestamps.

Method 1: Querying via HTTP API with cURL

The fastest way to test the snapshot functionality is through a direct HTTP request. This approach requires no client libraries and works with standard command-line tools.

curl -X GET "http://localhost:8000/api/temporal/snapshot?at=2025-06-15T00:00:00"

The response contains the full graph structure as it existed at the specified timestamp, including all node properties and edge relationships that were valid at that point.

Method 2: Frontend JavaScript Implementation

The Explorer UI fetches snapshots directly when users navigate to historical positions. The implementation in explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx (lines 1540-1545) demonstrates the standard fetch pattern used by the frontend.

async function fetchSnapshot(atIso) {
  const url = `/api/temporal/snapshot?at=${encodeURIComponent(atIso)}`;
  const response = await fetch(url);
  if (!response.ok) throw new Error('Snapshot request failed');
  const snapshot = await response.json();
  return snapshot;   // { nodes: [...], edges: [...], ... }
}

// Example usage
fetchSnapshot('2025-06-15T00:00:00')
  .then(snap => console.log('Graph snapshot:', snap));

This pattern handles URL encoding automatically and parses the JSON response into a usable graph object containing nodes and edges arrays.

Method 3: Python Client Script

For programmatic access within Python applications, use the requests library to interact with the snapshot endpoint. This approach is ideal for data analysis pipelines or backup scripts.

import requests

def get_snapshot(at: str | None = None):
    params = {'at': at} if at else {}
    resp = requests.get(
        'http://localhost:8000/api/temporal/snapshot', 
        params=params
    )
    resp.raise_for_status()
    return resp.json()

# Example: fetch the graph as of 15 June 2025

snapshot = get_snapshot('2025-06-15T00:00:00')
print(snapshot)

The function defaults to the current time when no timestamp is provided, matching the endpoint's native behavior.

Method 4: CLI Skill Invocation

Semantica ships with a built-in temporal skill that wraps the HTTP API for command-line usage. As documented in plugins/skills/temporal/SKILL.md, this skill provides convenient syntax for snapshot retrieval.

# Obtain a point-in-time snapshot and pretty-print it

semantica:temporal snapshot --at 2025-06-15T00:00:00 | jq .

This method handles authentication and endpoint configuration automatically, using the local Semantica instance's default settings.

Key Implementation Files

The following source files define and test the snapshot functionality:

• explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx (lines 1540-1545): Contains the React component logic that requests snapshots when users navigate to temporal positions in the Explorer interface.

• tests/explorer/test_explorer_api.py (lines 518-531): Houses integration tests verifying that the snapshot endpoint correctly reconstructs historical graph states from various timestamps.

• docs/reference/explorer.md: Provides the official API reference documentation for the GET /api/temporal/snapshot endpoint and its parameter specifications.

• plugins/skills/temporal/SKILL.md: Defines the CLI skill interface, documenting command syntax and usage examples for the semantica:temporal snapshot command.

Summary

• The GET /api/temporal/snapshot endpoint returns complete graph states for any valid ISO-8601 timestamp provided via the at query parameter.
• The GraphWorkspace component in GraphWorkspace.tsx implements the standard frontend pattern for fetching snapshots during temporal navigation.
• Python clients can retrieve snapshots using standard HTTP libraries, with optional timestamp parameters defaulting to the current time.
• The Semantica CLI provides a wrapped semantica:temporal snapshot command for command-line automation and scripting.
• Integration tests in test_explorer_api.py confirm that historical state reconstruction functions correctly across the bi-temporal data model.

Frequently Asked Questions

What timestamp format does the Semantica snapshot endpoint require?

The endpoint accepts any valid ISO-8601 timestamp (e.g., 2025-06-15T00:00:00). The system parses this string according to standard datetime conventions and retrieves the graph state valid at that exact moment.

How do I retrieve the current state without specifying a timestamp?

Omit the at parameter entirely. According to the API documentation in docs/reference/explorer.md, the endpoint defaults to the current system time when no timestamp is provided, returning the most recent graph state.

Which source file handles snapshot requests in the Explorer frontend?

The GraphWorkspace.tsx file located at explorer/src/workspaces/GraphWorkspace/ contains the fetch logic at lines 1540-1545. This component calls /api/temporal/snapshot whenever users interact with the temporal navigation controls.

Can I automate snapshot retrieval using the Semantica CLI?

Yes. The semantica:temporal snapshot command documented in plugins/skills/temporal/SKILL.md enables scripted snapshot extraction. Combine this with tools like jq or redirection operators to process or store the JSON output in automated workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}