# The EndlessAI Platform

> EndlessAI is a video intelligence platform. It watches your videos and cameras against your goals and policies, and delivers alerts, reports and answers with video evidence — in the app, in WhatsApp, Telegram or Slack, through a REST API, and through an MCP server for AI agents. Usage is prepaid in platform tokens: $1 buys 1,000 tokens, at one price in the app, the API and MCP.

## Pages

- [Overview](https://platform.endlessai.com/build/): what the platform does and how it works
- [Get started](https://platform.endlessai.com/build/start/): from sign-up to a first answer, no code needed
- [Pricing](https://platform.endlessai.com/build/pricing/): token pricing, spending caps and the launch package
- [API quickstart](https://platform.endlessai.com/build/api/): from a video to an answer over REST
- [API reference](https://platform.endlessai.com/build/api/reference/): every public operation, with examples
- [MCP server](https://platform.endlessai.com/build/mcp/): connect Claude, Codex or any MCP client
- [Create an account](https://platform.endlessai.com/register)

## The Platform by EndlessAI — MCP Server

Endpoint (hosted): POST https://platform.endlessai.com/mcp — streamable HTTP, stateless, no sessions.
Local (stdio): node dist/stdio.js, env SUPERVISION_API_KEY (+ optional SUPERVISION_BASE_URL, default https://platform.endlessai.com).
Auth header: X-Api-Key: <credential>. Every request must carry it; no cookies/sessions.

Credentials:
- svk_... = project-scoped API key. project_id optional on every tool (defaults to bound project). Cannot list/create projects. Recommended default. Mint in the platform UI: Developers page (https://platform.endlessai.com/developers -> choose a project -> Create key) or project -> Settings -> Access (value shown once).
- svt_... = user-scoped token, all projects. project_id required on every tool except create_project/list_projects. Power-user only.

Credential check: the credential is verified during MCP initialize, not deferred to the first tool call — a bad key fails the handshake with a message naming the header it was read from and pointing at https://platform.endlessai.com/developers to mint a new one. An unknown key and a key for a project that no longer exists are answered identically.

Rate limit: 120 requests/minute per credential. 429 + Retry-After when exceeded; polling tools use a 5s floor.
Hosted cap: a single hosted tools/call is limited to ~60s by the CDN. Every tool that can exceed it returns a resume id rather than hanging (see the poll/resume convention below); no work is lost when a wait expires.
Public doc: GET https://platform.endlessai.com/llms.txt serves this file, text/plain, no auth.

Tools (19; ⚠ = spends tokens):
- list_projects: list accessible projects
- create_project: create a project (svt_ only)
- get_project_config: read whitelisted analysis config (smart_scan, first_pass.auto_trigger, strategy.watch_for)
- update_project_config: read-modify-write update of that same whitelisted config
- list_videos: paginated video list for a project
- get_video_status: single video processing status
- upload_video_from_url: ⚠ ingest video from a public URL; polls to terminal status; resume with get_video_status
- upload_video_file: ⚠ upload a local file path (stdio-only, multipart; not on hosted transport)
- trigger_smart_scan: ⚠ run a Smart Scan on a video: scene descriptions and summaries (dry_run:true = plan only, nothing is spent; returns run_id if the plan outlasts wait_seconds, default 45s)
- get_smart_scan_results: scan status + summary merged (by video_id), or a dry-run plan (by run_id)
- search_frames: find moments in a project's videos from a text description, or moments that look like a reference frame
- search_scenes: text search over a project's scenes
- list_face_persons: list face-gallery persons for a project
- label_face_person: set/clear a face-gallery person's label
- trigger_face_scan: ⚠ find the faces in a video and add them to the project's face gallery
- get_usage: token/cost usage for a project, optional per-event list
- ask_video_agent: ⚠ expensive, can take several minutes; the video agent answers a question about the project's videos with multi-step reasoning; returns answer or run_id
- get_agent_run: poll/resume a prior ask_video_agent run by run_id; a completed run may also carry `correction` (a self-check found the run's own evidence contradicts the answer — the correction wins)
- get_conclusions: site knowledge recorded for a project — claims from prior analyses with status (verified/proposed/refuted/stale), provenance and evidence refs; a claim is not a fact, quote `text` (returns enabled=false when site knowledge is off)

Poll/resume convention: long ops return partial state + an id on timeout rather than failing.
- upload_video_from_url -> poll via get_video_status(video_id)
- trigger_face_scan -> poll via trigger_face_scan again or check gallery later
- trigger_smart_scan dry_run -> on timeout returns run_id -> resume via get_smart_scan_results(run_id)
- ask_video_agent -> on timeout returns run_id -> resume via get_agent_run(run_id)
Only one active ask_video_agent run allowed per credential at a time.

Cost tools (spend tokens): upload_video_from_url, upload_video_file, trigger_smart_scan (unless dry_run), trigger_face_scan, ask_video_agent (most expensive). All list_*/get_*/search_* tools spend no tokens. Check spend with get_usage.
Out of tokens: 402 = the project's token balance or monthly spending cap is exhausted. Paid tools pause; read tools keep working. A human tops up or raises the cap in the platform (project -> Billing tab -> Monthly spending cap).

Raw REST (same auth, when MCP is not enough): base https://platform.endlessai.com/api/v1, header X-Api-Key (or Authorization: Bearer). Start with GET /me -> {project_id}. Golden path: GET /projects/:pid/videos · POST /projects/:pid/videos/upload-from-url {url} · GET /projects/:pid/videos/:vid/status · POST+GET /projects/:pid/videos/:vid/smart-scan · GET /projects/:pid/frames/search?q= · GET /projects/:pid/scenes/search?q= · POST /projects/:pid/agent/ask {question, video_id?} -> 202 {run_id, poll} -> GET /projects/:pid/agent/runs/:runId (>=5s apart; 409 on a second ask carries the in-flight run_id; run records live ~60min) · GET /projects/:pid/usage.