Using the REST API

An HTTPS JSON API with bearer-token auth. Here are the conventions every endpoint follows.

Every request goes to https://api.embodiflow.io/v1 with Authorization: Bearer <token>, using a personal access token or an API key. You can download the OpenAPI document from /openapi.json, or browse it in all endpoints.

Conventions

Once you know these few rules, every endpoint feels the same:

Lists come back one page at a time, sized by pageSize (default 25, maximum 100). If the response has a nextPageToken, pass it as pageToken to get the next page. Page through a collection rather than trying to read it in one call.
Errors look like { code, message }. The code is stable, so branch on it rather than on the message.
Some writes accept an Idempotency-Key header. Sending the same key with the same body returns the first result, so retries are safe.
On 429, wait for the time in Retry-After, then retry.
Paths are nouns, and actions are modelled as resources, for example .../submission-requests.
Operation summaries and field descriptions come straight from the OpenAPI document, so they are in English in every language of this site.

Groups

Projects

Create and manage projects, membership, and project metadata.

Recordings

Recordings, versions, retention, diffs, and health dimensions.

Upload

Upload sessions and batches that create recordings.

Search

Search across projects, with facets and previews.

Health and tasks

Annotation, review, repair tasks, and quality-rule preview.

Workflows

Templates, runs, container runs, triggers, and processor catalog.

Artifacts and export

Artifacts, download sessions, and training jobs.

Billing and usage

Subscriptions, entitlements, meters, and usage ledger.

Team and governance

Team lifecycle, legal hold, storage reconciliation, and users.

Episodes and versions

Episodes, dataset versions, version aliases, and composition profiles.

Annotation

Annotation jobs, the annotation schema, and the skill taxonomy.

Algorithms

Team algorithms, their versions, and registry access for algorithm images.

Models

Models, checkpoints, evaluations, and cancellation.

Account and notifications

Your profile, your assigned work, notifications, and activity.

Webhooks

Conventions

Once you know these few rules, every endpoint feels the same:

Lists come back one page at a time, sized by pageSize (default 25, maximum 100). If the response has a nextPageToken, pass it as pageToken to get the next page. Page through a collection rather than trying to read it in one call.
Errors look like { code, message }. The code is stable, so branch on it rather than on the message.
Some writes accept an Idempotency-Key header. Sending the same key with the same body returns the first result, so retries are safe.
On 429, wait for the time in Retry-After, then retry.
Paths are nouns, and actions are modelled as resources, for example .../submission-requests.
Operation summaries and field descriptions come straight from the OpenAPI document, so they are in English in every language of this site.