API reference

The hosted API is at https://api.euler.sudotank.com. It serves its own schema and interactive explorer:

https://api.euler.sudotank.com/openapi.json
https://api.euler.sudotank.com/docs

The versioned contract is committed at openapi/euler.openapi.json. Generated clients live in sdks/typescript and sdks/python; release tags publish them only when the repository has npm and PyPI tokens configured.

This page maps the surfaces by area. It is a map, not a substitute for the schema: request and response shapes come from openapi.json.

Conventions

• Everything under /v1 is tenant-scoped. The tenant comes from the caller’s principal, never from a path or query parameter.
• Roles form an ordered ladder: viewer < reviewer < engineer < admin. Reads generally need viewer, ingest and pipeline writes need engineer, review decisions need reviewer, and tenant administration needs admin.
• Mutations are recorded in the audit log.
• Errors use standard codes. 402 means the tenant’s weekly model budget would be breached, 409 means a conflicting state such as a layer that is turned off, and 422 means the request named something the platform does not recognise.

export EULER_BASE_URL="https://api.euler.sudotank.com"
export EULER_TOKEN="…"
curl -fsS -H "Authorization: Bearer $EULER_TOKEN" "$EULER_BASE_URL/v1/projects"

Health

Tenancy, identity and access

Workspaces and projects

Sources, uploads and runs

Annotation

See annotation layers, pipeline settings, annotation jobs and the automated review pass.

Re-derivations from stored data (no GPU, no spend; send a few episodes per call):

annotation_review is a valid layer_id on the jobs endpoint and is not an annotation-catalog layer; it grades what the other layers produced.

Synchronous per-episode annotation surfaces remain available alongside the queue:

Readiness, utility and certification

See readiness and data utility.

Episodes, review and media

Paging episodes

The plain list returns every episode in full. For anything larger than a handful, ask for slim rows a page at a time and fetch one episode in full when you need it:

curl -fsS -H "Authorization: Bearer $EULER_TOKEN" \
  "$EULER_BASE_URL/v1/projects/$PROJECT/episodes?fields=summary&page=1&page_size=100"
curl -fsS -H "Authorization: Bearer $EULER_TOKEN" \
  "$EULER_BASE_URL/v1/projects/$PROJECT/episodes/$EPISODE"

A summary page carries total and pages. Each row has the episode id, session id, start, end and duration, frame rate and count, task, a short caption, data kind, review decision, readiness score, flags, the worst certificate status and the rules behind it, counts (labels, tracks, sub-tasks, dense actions, hand and body tracks, cameras) and the layers with stored output. page_size defaults to 50 and is at most 500. Episode ids may contain a slash; send them as they are.

Review surface

The routes the review screen reads. Every time is in the episode’s stored source-clock seconds, the same clock as every annotation. Each data route has a signed twin (telemetry-stream, signals-stream, frame-stream, artifact-stream) that takes ?token= from POST .../media-token instead of a header, for an image tag or a canvas.

E="$EULER_BASE_URL/v1/projects/$PROJECT/episodes/$EPISODE"
curl -fsS -H "Authorization: Bearer $EULER_TOKEN" "$E/telemetry?streams=ACCL,GYRO,GRAV,CORI&points=1200"
curl -fsS -H "Authorization: Bearer $EULER_TOKEN" "$E/signals?points=600&t0=20&t1=50"
curl -fsS -o frame.jpg -H "Authorization: Bearer $EULER_TOKEN" "$E/frame?t=42.5&w=640"
curl -fsS -H "Authorization: Bearer $EULER_TOKEN" "$E/layers/threed/artifact?part=trajectory"

Telemetry. streams defaults to ACCL,GYRO,GRAV,CORI (accelerometer, gyroscope, gravity, camera orientation); the camera may also record ISOE, SHUT and YAVG (exposure). points is 1200 by default (10 to 5000); t0/t1 zoom into a window. Each stream is {name, columns, units, rate_hz, n_raw, bucket_s, t, min, max, mean}, where min/max/mean map each column to one value per bucket, so a one-sample spike survives. Empty buckets are left out, never zero-filled. derived adds gyro_mag, accel_mag, tilt_deg and yaw_deg/pitch_deg/roll_deg. withheld names streams that are never served (location and face); missing names requested streams the recording does not have. No telemetry at all is a 404 with the reason.

Signals. The same block shape under streams: hand_presence_left/right, hand_speed_left/right, object_count, head_speed_mps (estimated) and head_angular_speed_dps. bands are sub-task, action and flagged spans (kind, start, end, label, and the check and severity for a flag); markers are instants (flags, depth keyframes).

Frame. t in stored seconds (422 outside the episode), w from 64 to 1280 (default 320). Returns image/jpeg, cached; fetch it as a file, not as JSON.

3D parts (?part= on the threed artifact):

The SDKs expose these as get_episode, episode_telemetry, episode_signals, episode_frame and episode_layer_artifact. Query parameters are not yet arguments of those methods; for paging, windows or parts use the client’s request with the full path:

rows = client.request("GET", f"/v1/projects/{project}/episodes?fields=summary&page=1&page_size=100")
traj = client.request("GET", f"/v1/projects/{project}/episodes/{episode}/layers/threed/artifact?part=trajectory")

Search, slices and curation

See curation and the search and slices recipe.

Exports

Copilot

See Euler Copilot.

The earlier planning surface remains available:

Models, budget and cost

GET /v1/models returns the active model per surface with its evidence and the vetted alternatives. PUT accepts only a vetted option on a selectable surface.