A Directive keeps the API version used to create it. To move a Directive from the Robots Beta API (v0) to the GA API (v1), create a new Directive with v1 configuration, test it, then replace the old Directive ID in your asset-creation integrations. The existing Directive does not change version.

Start with the Robots API migration guide for workflow parameter and output changes. Update and deploy webhook handlers before starting v1 runs. See the Directives API referenceAPI for the complete configuration.

Choose how to create the v1 copy

From the Dashboard

Open an existing v0 Directive and choose Create v1 copy. Review the workflows, resources, and options, then create the new Directive. Legacy options that v1 no longer supports are omitted from the copy. Remove workflows unavailable in v1, such as Find Scenes, before creating it; replace scene analysis with Analyze Structure where appropriate.

The copy has a new ID. The v0 Directive stays in place, and integrations that attach its ID keep triggering it. Creating a copy does not move asset references, modify external integrations, or delete the original.

From the API

1. Fetch the existing configuration through GET /robots/v0/directives/{DIRECTIVE_ID}.
2. Convert it using the mappings below. Send configuration fields only, omitting response metadata such as id, timestamps, and _links.
3. Create the replacement with POST /robots/v1/directives.
4. Store the returned v1 Directive ID alongside its API version.

Convert the configuration

Binding workflow, binding/resource reference_id, inputs[], and source.binding keep their names. Preserve reference IDs so dependencies still resolve. Don't put asset_id or the source track_id in binding parameters; the Directive supplies them.

Apply the workflow parameter changes inside every binding too: translation targets become output_language_code, key-moment target durations become seconds, and deprecated fields are removed. Replace find-scenes bindings with an appropriately configured analyze-structure binding.

For example, this v0 configuration generates a caption resource, then translates it:

{
  "name": "Generate and translate captions",
  "subject": { "type": "video.asset" },
  "resources": [
    {
      "reference_id": "captions_en",
      "type": "video.asset.track",
      "kind": "caption",
      "language": "en",
      "source": {
        "via": "mux_api",
        "action": "generate_subtitles",
        "params": {
          "language_code": "en",
          "source_audio_language": "en-US"
        }
      }
    }
  ],
  "workflows": [
    {
      "reference_id": "translate_es",
      "workflow": "translate-captions",
      "inputs": ["captions_en"],
      "params": { "to_language_code": "es" }
    }
  ]
}

Save this v1 configuration as directive-v1.json:

{
  "name": "Generate and translate captions v1",
  "subject": { "type": "video.asset" },
  "resources": [
    {
      "reference_id": "captions_en",
      "type": "video.asset.track",
      "kind": "subtitles",
      "language_code": "en",
      "source": {
        "via": "mux_api",
        "action": "generate_subtitles",
        "parameters": {
          "language_code": "en",
          "source_audio_language_code": "en-US"
        }
      }
    }
  ],
  "bindings": [
    {
      "reference_id": "translate_es",
      "workflow": "translate-captions",
      "inputs": ["captions_en"],
      "parameters": { "output_language_code": "es" }
    }
  ]
}

Create it through v1:

curl https://api.mux.com/robots/v1/directives \
  -u "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d @directive-v1.json

Unknown fields are ignored, so a successful create request does not mean obsolete optional fields still take effect. Review the resulting configuration and its behavior on a test asset.

Update list and detail handling

GET /robots/v1/directives returns slim summaries of both v0 and v1 Directives, with id, name, created_at, updated_at, and _links.self. It no longer returns the full configuration in every list entry.

Follow _links.self.href to get the full configuration. A summary with a /robots/v0/directives/... link still represents a v0 Directive even though you discovered it through the v1 list. The v0 list continues returning full v0 configurations.

Individual detail, delete, and run routes require the version that created the Directive. A version mismatch returns 404; the v1 detail endpoint only returns v1 Directives. Keep the version that created each Directive with any saved Directive ID. If an older saved link contains only an ID, try the v1 detail endpoint and fall back to v0 only on 404, not authentication or server errors.

For a v0 Directive, keep using /robots/v0/directives/{id}/runs and its run-detail routes while it remains active. For a v1 Directive, use the corresponding v1 routes.

Update run-response parsing

V1 uses one run representation across start responses, lists, detail reads, and webhook data. It includes id, directive_id, subject_id, status, node_states, started_at, and completed_at.

source_bindings[] contains binding reference IDs, not workflow names. Node failure details remain in reason. Run timestamps are still Unix seconds. The manual start request still uses { "asset_id": "YOUR_ASSET_ID" }; subject_id is a response field, not a renamed request parameter.

Child jobs inherit the Directive's version. Fetch their details through that version too, rather than assuming that every job visible in your dashboard or list is v1.

Test and switch automatic triggers

A Directive triggers automatically when its ID is attached to an asset at creation. Test the new Directive, then switch those attachments to its ID.

1. Run the new Directive manually against a test asset:

curl https://api.mux.com/robots/v1/directives/YOUR_V1_DIRECTIVE_ID/runs \
  -u "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "asset_id": "YOUR_TEST_ASSET_ID" }'

2. Verify the v1 run, its child-job outputs, and the robots.v1.directive_run.* and robots.v1.job.* webhook handlers. V1 caption track selection rules also apply when a Directive dispatches jobs.
3. Replace the v0 Directive ID in asset-creation requests, upload settings, templates, and any stored integration configuration with the new v1 ID. The Video API route itself does not change:

curl https://api.mux.com/video/v1/assets \
  -u "$MUX_TOKEN_ID:$MUX_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "url": "https://example.com/my-video.mp4" }],
    "playback_policies": ["public"],
    "directives": [{ "id": "YOUR_V1_DIRECTIVE_ID" }]
  }'

4. Confirm a newly created asset triggers the v1 Directive. A Directive runs on the version that created it; there is no version field to add to the Video request's directives[] entry.
5. Keep v0 history and webhook handling available until the old Directive has stopped running and outstanding deliveries have arrived. Delete the old Directive through its v0 route once you no longer need new runs from it.

To roll back during the v0 support period, restore the old v0 ID in the integrations that create assets. Keep the original Directive until you have verified the cutover; deleting it removes that rollback option.

Migration checklist

• Every binding and source uses the v1 field names and units.
• Legacy options and workflows unavailable in v1 have been reviewed or replaced.
• The new Directive has been tested manually, including caption track selection and asset updates.
• List consumers fetch configuration through _links.self.
• Run parsers and child-job reads use the correct version.
• Webhook handlers accept both v0 and v1 events.
• Asset-creation integrations reference the new v1 Directive ID.
• A newly uploaded asset has successfully triggered the new Directive.