Skip to main content
POST
Generate Moment

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.

Request Body

string
required
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”
string
default:"default"
Flash API preset controlling generation quality and detail level.Available presets:
  • default - Standard generation
  • balanced - Balanced quality and speed
  • detailed - Maximum detail and accuracy
string
default:"private"
Visibility level for the generated moment.Options:
  • private - Only visible to creator
  • public - Visible to all users

Response

string
Unique identifier for the generation job. Use this with the Get Job endpoint to check status.
string
Current job status. Will be pending immediately after creation.Possible values:
  • pending - Job created, waiting to process
  • processing - Currently generating moment
  • completed - Successfully generated and indexed
  • failed - Generation failed (check error field)
string
ISO 8601 timestamp when the job was created.
string | null
Graph path where the moment will be indexed. Only available when status is completed.Format: /YYYY/month/DD/HHMM/country/region/city/event-slug
string | null
Error message if status is failed. Otherwise null.
string | null
ISO 8601 timestamp when job finished (completed or failed). null while processing.

Example Request

Example Response

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:
  1. Store the job_id from the response
  2. Poll the Get Job endpoint
  3. 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