DEVELOPER DOCUMENTATION · v1

One request in.
One timestamp out.

The ChronoSeek API turns natural language into frame-accurate video timestamps. This page covers everything you need to make your first call and ship.

Getting started

This is the proposed v1 contract. The public API will be backed by the ChronoSeek subnet once validator and gateway implementation is complete.

base url

https://api.chronoseek.org/v1

Authentication examples below are part of the preview contract; public API keys are not being issued yet.

Authentication

Authenticate every request with a bearer token in the Authorization header. Requests without a valid key return 401.

header

Authorization: Bearer cs_live_9f2e…

Quickstart

Find a moment in a hosted video with one call:

curl

curl -X POST https://api.chronoseek.org/v1/seek \
  -H "Authorization: Bearer $CHRONOSEEK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/match.mp4",
    "query": "the moment the goalkeeper saves the shot"
  }'

POST /v1/seek

Search one video for one described moment.

Field	Type	Description
`video_url`	string	Public or signed URL of the video. MP4, WebM, MOV, HLS.
`video_id`	string	ID of a previously indexed video. Use instead of `video_url` for long footage.
`query`	string	Plain-language description of the moment. Be concrete: actions, objects, sounds.
`top_k`	int	Candidate moments to return. Default `3`, max `10`.
`min_confidence`	float	Drop candidates below this score. Default `0.3`.

The response

The primary result is first; candidates holds the runner-up moments so you can offer "did you mean this scene?" navigation.

200 OK

{
  "timestamp": "00:47:12.480",
  "timestamp_seconds": 2832.48,
  "confidence": 0.97,
  "window": ["00:47:09.100", "00:47:18.220"],
  "candidates": [
    { "t": "00:47:12.480", "confidence": 0.97, "miner_uid": 26 },
    { "t": "00:12:48.960", "confidence": 0.44, "miner_uid": 9 }
  ],
  "miners_queried": 42,
  "latency_ms": 812
}

window is the span the network agrees contains the full action — seek there when you want context, to timestamp when you want the frame.

Indexing long videos

For footage over ~30 minutes, index once and query many times. Indexing runs asynchronously; poll the job or register a webhook.

POST /v1/videos

curl -X POST https://api.chronoseek.org/v1/videos \
  -H "Authorization: Bearer $CHRONOSEEK_KEY" \
  -d '{ "video_url": "https://example.com/full-match.mp4" }'

# → { "video_id": "vid_8f31c2", "status": "indexing" }
# then query it forever:
# POST /v1/seek  { "video_id": "vid_8f31c2", "query": "…" }

Errors

Code	Meaning	What to do
`400`	Malformed request	Check required fields; exactly one of `video_url` / `video_id`.
`401`	Invalid API key	Regenerate the key from your account page.
`404`	Video not reachable	The URL must be publicly fetchable or a signed link.
`422`	No confident moment	The network found nothing above `min_confidence`. Rephrase with concrete detail.
`429`	Rate limited	Back off per `Retry-After`; see limits below.

Rate limits

Plan	Seeks / min	Indexing hours / day
Developer	20	2
Scale	300	50
Network partner	custom	custom

Every response carries X-RateLimit-Remaining. Need more? Follow the GitHub organization or run your own validator for priority access.

TRY IT IN THE PLAYGROUND READ THE WHITEPAPER

One request in.One timestamp out.