API reference

A complete beta API path for video World-State products.

Endpoint groups, authentication, tenancy, idempotency, response envelopes, artifact versions, Ask Video rules, and production-readiness checks.

Endpoint groups

Method	Path	Purpose
POST	/api/videos/add	Create a video source record from URL, HLS, or recording metadata.
GET	/api/product/videos	List tenant-scoped video records and current status.
POST	/api/product/videos/{video_id}/execute	Run bounded CPU-first processing and materialize artifacts.
GET	/api/product/videos/{video_id}/scene-graph	Return structured World-State objects, events, confidence, and evidence refs.
GET	/api/product/videos/{video_id}/timeline	Return ordered events and semantic refresh markers.
GET	/api/product/videos/{video_id}/evidence-view	Return evidence spans and review notes.
POST	/api/product/videos/{video_id}/ask	Ask a question with evidence-required guardrails.
GET	/api/product/videos/{video_id}/cost	Return cost.json, detector mode, duration, fallback, and retention.
GET	/api/product/billing/state	Return sandbox limits and current usage state.

Authentication and tenancy

All product APIs are tenant-scoped. API keys should be backend secrets. Browser applications should call your backend, and your backend should call Ayneye with the correct tenant context. Store video_id and execution_id alongside your own project or customer object so support teams can audit later.

Dashboard sessions and API keys can coexist, but they should not be mixed casually. The dashboard is useful for manual inspection and onboarding. API keys are useful for server-to-server integration. Both should preserve evidence and cost visibility.

Idempotency and retries

Source creation and execution requests should include an idempotency key when the client may retry. A network timeout should not create duplicate videos or executions. If the API returns ARTIFACT_NOT_READY, poll or show a waiting state instead of retrying the entire execution blindly.

Request and response models

Source request

{
  "url": "https://example.com/video.mp4",
  "title": "loading zone camera 7",
  "source_type": "url|hls|recording|demo",
  "external_source_id": "camera-7-2026-06-24",
  "metadata": {"site": "warehouse-a", "zone": "loading-zone"}
}

Standard response envelope

{
  "ok": true,
  "request_id": "req_...",
  "video_id": "vid_...",
  "execution_id": "exe_...",
  "artifact_version": "art_...",
  "evidence_refs": ["ev_001"],
  "review_required": false
}