Skip to content

Integration overview

For frontend engineers and platform teams connecting a web application or edge agent to CowCow.

Architecture

Browser  →  Your UI  →  CowCow HTTP API (/v1/*)
                 ↑
         optional server-side proxy (recommended for API keys)

Your UI should call CowCow over HTTP. Do not expose object-storage credentials or upstream dataset APIs in the browser. Sample metadata, media streams, sync jobs, and efficiency reports come from CowCow /v1 routes.

Layer Role
Your UI Tables, previews, sync controls
CowCow API Ingest, sync, verify, reports
OpenAPI Machine-readable contract at /v1/openapi.json

Authentication

When API keys are enabled (typical in production), send them from a server-side proxy only:

Header Value
X-API-Key key configured in your deployment
or Authorization Bearer <same key>

Public (no key): GET /health, GET /ready, GET /metrics, GET /v1/openapi.json

Core API routes

UI need Route
Project list GET /v1/projects
Sample table GET /v1/projects/{id}/samples
Sample detail + QC/priority GET /v1/projects/{id}/samples/{sample_id}
Video/image stream GET /v1/projects/{id}/samples/{sample_id}/media
JPEG preview GET /v1/projects/{id}/samples/{sample_id}/preview
Start sync job POST /v1/projects/{id}/sync-jobs
Job progress GET /v1/projects/{id}/jobs/{job_id}
Live sync animation GET /v1/projects/{id}/sync/stream (SSE)
Sync snapshot GET /v1/projects/{id}/sync/status
Dataset report GET /v1/projects/{id}/reports/dataset
Sync efficiency GET /v1/projects/{id}/reports/sync

Sync jobs

Typical flow:

  1. POST /v1/projects/{id}/sync-jobs with destination, priority list, and resume: true
  2. Worker uploads BLAKE3 chunks to your configured object store, skipping verified bytes
  3. UI polls job status and GET /v1/projects/{id}/reports/sync for skip rate and throughput

Required body fields: destination, priority, resume.

Example body:

{
  "destination": "s3://your-bucket/your-prefix",
  "priority": "urgent,high,normal",
  "resume": true
}

Reference demo project

The public demo deployment uses project id physicalai-demo. Useful constants when exploring the API:

Constant Value
Project ID physicalai-demo
Example sensor camera_front_wide_120fov
Video samples 128 (paginate with limit=100)
Media GET /v1/projects/physicalai-demo/samples/{sample_id}/media
Preview GET /v1/projects/physicalai-demo/samples/{sample_id}/preview

Example list call:

GET /v1/projects/physicalai-demo/samples?modality=video&sensor_id=camera_front_wide_120fov&limit=100

Replace project id, bucket paths, and auth with your own deployment values.