One real run, end to end.

A limited real-execution API. Successful run results come only from the installed provenance-stamped percept-vision wheel; zero incidents is a valid result. Run results are not mocked or predetermined.

Base URL

https://percept-cloud-demo-api-299322077893.us-west2.run.app

Authentication

Bearer token on every endpoint except /v1/healthz, which is unauthenticated. The token is the meeting demo token or a provisioned client API key.

Use GET /v1/healthz as the health endpoint. The bare /healthz path is intercepted by the platform edge and returns an HTML 404 before reaching the service, so probe /v1/healthz.

Authorization: Bearer <token>

Endpoints

POST /v1/runs — multipart fields

Content type multipart/form-data. Provide exactly one of media or sample_id — never both. Uploaded media is limited to 10 minutes (600 s) and 25 MiB; longer media fails the run and an oversized file returns 413 upload_too_large. Both live caps are published at GET /v1/meta as limits.max_media_seconds and limits.max_upload_bytes.

source_profile tunes cognition for the kind of footage — physical_scene (default) for cameras and the real world, or screen_document for screen captures and documents. execution_policy is optional and biases how the run spends its budget: balanced, burst, low_cost, or privacy_edge.

Run lifecycle

queued -> running -> succeeded | failed

202 returns a RunAccepted; poll its poll_url until status is terminal. A succeeded run with incidents: [] is a valid result — the goal's condition never became true, and the system does not fabricate a fire.

While status is running, the run streams a partial trace (and any incidents so far) into each poll response, so a client watches the ledger fill live instead of waiting on a blank panel. The final post-run write is authoritative.

Create + poll

# 1. Create a run (multipart): your media OR a hosted sample, plus a plain-language goal.
curl -s -X POST https://percept-cloud-demo-api-299322077893.us-west2.run.app/v1/runs \
  -H "Authorization: Bearer $PERCEPT_TOKEN" \
  -F "media=@meeting.mp4" \
  -F "goal=tell me when the red panel is uncovered" \
  -F "evidence_modality=fused" \
  -F "vision_provider=gemini"
# 202 -> {"id":"<run_id>","status":"queued","poll_url":"/v1/runs/<run_id>"}

# 2. Poll until status is terminal (queued -> running -> succeeded | failed).
curl -s https://percept-cloud-demo-api-299322077893.us-west2.run.app/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $PERCEPT_TOKEN"
# 200 -> {"status":"succeeded","incidents":[...],
#         "provenance":{"package":"percept-vision","entrypoint":"percept.run",
#                       "result_kind":"real_oss_execution", ...}}

Sample-based variant: replace the media field with -F "sample_id=red-panel" (never send both).

Response schemas

RunAccepted

Required: id, status (const queued), poll_url.

Run

Required: id, project_id, status (queued|running|succeeded|failed), goal, evidence_modality (vision|audio|fused), media_filename, created_at, incidents (array of objects). Also: vision_provider (gemini|openrouter), source_profile (physical_scene|screen_document), execution_policy (balanced|burst|low_cost|privacy_edge or null), started_at / completed_at (nullable date-times), trace (nullable object — streams live while running), provenance (OssProvenance or null), error (nullable object).

OssProvenance

The proof the result came from the real OSS wheel. Required: package (const percept-vision), package_version, git_commit, contract_version, build_timestamp, entrypoint (const percept.run), provider, model, result_kind (const real_oss_execution).

Sample

Required: id, label, media_type (const video/mp4), duration_seconds, has_audio, suggested_goal, sha256.

Error

{"error": {"code", "message", "correlation_id"}} — all three required. Every error carries a correlation_id; include it when reporting a problem.