Use this guide to move an existing integration from the Robots Beta API (/robots/v0) to the GA API (/robots/v1). V1 changes request fields, response shapes, caption track selection, and webhook event types. Changing the API URL alone is not enough.

The Robots v0 API is deprecated and remains available for six months after the v1 launch. Existing jobs and directives are tied to the API version used to create them. Creating v1 resources does not migrate existing v0 resources.

If you also use Directives or Robots webhooks, follow Migrate Robots Directives from Beta to GA and Migrate Robots webhooks from Beta to GA. See the Robots API referenceAPI for the full contracts.

Plan your rollout

During the migration, v0 and v1 run side by side. Jobs and Directives you already have stay on v0, while anything you create through v1 returns v1 response shapes and sends v1 webhook events. Follow these steps in order so your integration can handle both versions at every stage, and so you can switch new requests back to v0 until the cutover is complete.

1. Update and deploy webhook handlers that accept both versions before creating v1 jobs or Directives.
2. Update request construction and response parsing using the mappings below. Store the API version that created each job or Directive alongside its ID.
3. Test v1 with representative assets, including assets with several caption tracks and any audio-only content you process.
4. Switch new job creation to v1. Continue reading and acting on existing v0 jobs through v0.
5. Create v1 replacements for any v0 Directives, then update the integrations that reference their IDs.
6. Keep v0 webhook handling while v0 Directives are still running or v0 webhook deliveries are still arriving.

Update request paths and parameters

Change new job requests from /robots/v0/jobs/{workflow} to /robots/v1/jobs/{workflow}. Mux API authentication, access tokens, and the parameters request envelope stay the same.

For example, key-moment duration preferences change from integer milliseconds to seconds.

V0 request:

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "target_duration_ms": { "min": 15000, "max": 45000 }
  }
}

V1 request:

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "target_duration": { "min": 15, "max": 45 }
  }
}

Update these fields wherever you construct workflow requests, including Directive binding parameters.

For edit-captions, preserving the source requires replace_existing_tracks: "fail" and a track_name different from the source track's name. The default v1 replacement policy is "replace". Review this explicitly if your v0 integration used the legacy naming or deletion options.

Unknown request fields are ignored, rather than treated as aliases. For example, sending only to_language_code to a v1 translation endpoint does not satisfy the required output_language_code field. Remove obsolete fields from your integration even when the request succeeds without them.

Update response parsing

These changes apply to both a job's GET response and the data object of its v1 webhook.

Read media times as seconds

Media offsets in v1 use seconds and can contain fractional values. These are positions on the original asset timeline, not Unix timestamps. A value of 23.456 represents the same position as 23456 milliseconds in v0.

Remove any existing millisecond-to-second conversion when reading v1 values, or playback positions will be scaled twice. Unix timestamps such as created_at and updated_at already use seconds and do not need this conversion. Chapter start times already use seconds too.

Read track IDs and asset update outcomes

replaced_track_ids contains IDs of tracks that were deleted. It is omitted when no deletions were recorded; do not assume it is always present. V1 no longer includes the metadata objects previously returned in replaced_tracks.

In caption editing and translation, parameters.track_id is the source track, while outputs.track_id identifies the newly created track.

Writing results back to the asset is best effort. A job can complete successfully while an asset update reports status: "failed", so check the corresponding asset_updates entry separately from the job status. Older jobs that recorded no update outcome omit it. For chapter replacement, a failed update with deleted track IDs means deletion succeeded but creation failed.

Review caption track selection

V1 uses the first ready caption track in asset track order, without preferring English. If your integration relied on the English preference, supply language_code explicitly when the workflow supports it.

An explicit source language_code must match exactly, including case and region. For example, en does not select an en-US caption track. When checking for an existing track in a translation's target language, or a track to replace, en and en-US count as the same language.

An explicit caption track_id must identify a ready caption track. Audio-only assets with exactly one ready text track that isn't marked as captions can use that track as a legacy transcript. Audio-only moderation no longer assumes language_code: "en" when you omit it.

Before switching production requests, test with assets that have multiple languages, text tracks that aren't captions, or captions that are still preparing. Jobs dispatched by a Directive follow the selection rules of the Directive's version.

Replace Find Scenes integrations

find-scenes is not included in the v1 release. Use Analyze Structure (POST /robots/v1/jobs/analyze-structure) and read outputs.scenes. Analyze Structure also produces a shared title, summary, tags, chapters, and key moments.

curl https://api.mux.com/robots/v1/jobs/analyze-structure \
  -u "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "asset_id": "YOUR_ASSET_ID" } }'

Update your scene parser for start_time and end_time in seconds, including nested cue and shot intervals. Review the Analyze Structure contract rather than copying Find Scenes parameters unchanged: its output steering and result structure are different, and generated scene boundaries can differ.

Keep existing jobs on the version that created them

The v1 jobs list can discover jobs created through either version. Each summary includes _links.self.href, which points to the route for the version that created the job:

{
  "id": "rjob_example",
  "_links": {
    "self": { "href": "/robots/v0/jobs/summarize/rjob_example" }
  }
}

This is an excerpt from a v1 list response. Follow the relative URL against https://api.mux.com rather than rebuilding it with /v1. List summaries do not contain full workflow parameters or outputs.

Detail and cancel requests must use the version that created the job. A v0 job requested through a v1 detail route returns 404; it is not converted into a v1 job on read. For cancellation, use POST /robots/{VERSION}/jobs/{JOB_ID}/cancel with that version.

Store the version that created each new job, and keep it in polling queues, saved job links, and retry/cancel actions. A v1 webhook identifies a v1-created job; a v0 webhook identifies a v0-created job.

Update error handling

Read error.messages[] instead of the removed error.message field. For example:

{
  "error": {
    "type": "track_not_ready",
    "messages": ["No ready subtitle track available for this asset"]
  }
}

Handle errors according to their type and status rather than matching message strings.

These readiness and duplicate-job types describe job creation. Other operations can return 409 for operation-specific conflicts, such as cancelling a job already in a terminal state.

Migration checklist

• New job requests use /robots/v1 and the renamed parameters.
• Request builders no longer send removed fields.
• Response parsers read seconds, v1 track IDs, and error.messages[].
• Caption track tests cover your actual languages and track order.
• Find Scenes integrations use Analyze Structure and its result schema.
• Job lists follow _links.self, and stored jobs keep the API version that created them.
• Webhook handlers that accept both versions are deployed before v1 creation starts.
• V0 Directives have v1 replacements. See Migrate Robots Directives from Beta to GA.