API reference — ChronoSeek

//01

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.

//02

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…

//03

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"
  }'

//04

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`.

//05

The response

The primary result is first; candidatesholds 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.

//06

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": "…" }

//07

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.

//08

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.