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 /generate endpoint accepts a natural language query describing a historical event and returns a job ID. The system uses the Flash Timepoint API to generate structured moment data, which is then indexed into the Clockchain graph.
Authentication
Requires SERVICE_API_KEY header for authentication.
X-Service-Key: your-service-api-key
Request Body
Natural language description of the historical event. Can include date and location hints.Examples:
- “Caesar’s assassination March 15 44 BC Rome”
- “Moon landing 1969”
- “Fall of the Berlin Wall”
Flash API preset controlling generation quality and detail level.Available presets:
default - Standard generationbalanced - Balanced quality and speeddetailed - Maximum detail and accuracy
Visibility level for the generated moment.Options:
private - Only visible to creatorpublic - Visible to all users
Response
Unique identifier for the generation job. Use this with the Get Job endpoint to check status. Current job status. Will be pending immediately after creation.Possible values:
pending - Job created, waiting to processprocessing - Currently generating momentcompleted - Successfully generated and indexedfailed - Generation failed (check error field)
ISO 8601 timestamp when the job was created.
Graph path where the moment will be indexed. Only available when status is completed.Format: /YYYY/month/DD/HHMM/country/region/city/event-slug
Error message if status is failed. Otherwise null.
ISO 8601 timestamp when job finished (completed or failed). null while processing.
Example Request
curl -X POST https://api.clockchain.io/api/generate \
-H "Content-Type: application/json" \
-H "X-Service-Key: your-service-api-key" \
-d '{
"query": "Signing of the Declaration of Independence July 4 1776",
"preset": "balanced",
"visibility": "private"
}'
Example Response
{
"job_id": "a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f",
"status": "pending",
"path": null,
"error": null,
"created_at": "2026-03-06T14:32:18.123456Z",
"completed_at": null
}
Content Moderation
If OPENROUTER_API_KEY is configured, queries are screened by a content judge before processing. Inappropriate queries will be rejected with a 400 error.
Job Processing
Generation jobs are processed asynchronously in the background. To check job status and retrieve the generated moment path:
- Store the
job_id from the response
- Poll the Get Job endpoint
- When
status is completed, use the path to fetch moment details
Generation can take 5-30 seconds depending on query complexity and the Flash API preset used. Implement appropriate polling intervals (recommended: 2-5 seconds).
Error Responses
| Status Code | Description |
|---|
| 400 | Query rejected by content judge |
| 401 | Missing or invalid SERVICE_API_KEY |
| 503 | Job manager not available |