--- title: "Get a directive" method: GET path: "/robots/v1/directives/{DIRECTIVE_ID}" tags: ["Directives"] --- # Get a directive `GET /robots/v1/directives/{DIRECTIVE_ID}` ## Request - Base URL: `https://api.mux.com` - URL: `https://api.mux.com/robots/v1/directives/{DIRECTIVE_ID}` - Auth: one of: - HTTP basic - HTTP bearer Returns a v1 directive. A directive owned by v0 returns 404. ## Path parameters - `DIRECTIVE_ID` string, required: Directive ID returned by directive creation or listing (drv_...). ## Response `200` V1 directive - DirectiveResponse - `data` Directive, required - `name` string, required: Human-readable directive name. - `subject` DirectiveSubject, required: Mux asset lifecycle subject. Live streams are not supported. - `type` 'video.asset', required - `resources` DirectiveResource[], required: Resources required by dependent workflow bindings. - union - DirectiveTrackResource - `reference_id` string, required: Customer-chosen resource identifier, unique within resources. Binding `inputs` entries reference this handle. - `type` 'video.asset.track', required: A caption or audio track on the asset. - `kind` 'subtitles' | 'audio', required: Match subtitle text tracks or audio tracks. Other text track types are not eligible. - `source` union: How the resource is materialized. Defaults to an external source. - DirectiveSourceExternal: Wait for an externally produced resource to become ready. - … - DirectiveSourceRequired: Require the resource to be ready when the run starts. - … - DirectiveSourceWorkflow: Wait for the declared producer binding and its resource. - … - union - … - `language_code` string: BCP 47 language code the track must match (e.g. "en"). When omitted, any language of the declared kind matches. - DirectiveShotsResource - `reference_id` string, required: Customer-chosen resource identifier, unique within resources. Binding `inputs` entries reference this handle. - `type` 'video.asset.shots', required: The asset's shot-detection output. - `source` union: How the resource is materialized. Defaults to an external source. - DirectiveSourceExternal: Wait for an externally produced resource to become ready. - … - DirectiveSourceRequired: Require the resource to be ready when the run starts. - … - DirectiveSourceWorkflow: Wait for the declared producer binding and its resource. - … - union - … - `bindings` DirectiveBinding[], required - union - AnalyzeStructureDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'analyze-structure', required: Workflow identifier used by POST /robots/v1/jobs/analyze-structure. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` AnalyzeStructureDirectiveBindingParameters: Parameters for analyze-structure, excluding engine-supplied asset_id and source track_id where applicable. - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `output_language_code` string: BCP 47 language code for generated text. Auto-detected from available evidence when omitted. - `output_steering` AnalyzeStructureOutputSteering: Curated controls that restrict Analyze Structure execution or guide its generated metadata without exposing raw prompt editing. The scope start is inclusive, the end is exclusive, and returned timestamps remain absolute. - … - `update_asset_meta` boolean: When true, writes the generated title to asset.meta.title after analysis. Defaults to false. Best-effort: a metadata-write failure does not fail the analysis. Check outputs.asset_updates.title for the outcome. - `update_asset_chapters` boolean: When true, replaces or creates the asset's chapters track after analysis. Defaults to false. Best-effort: a chapters-write failure does not fail the analysis. Check outputs.asset_updates.chapters for the outcome. - SummarizeDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'summarize', required: Workflow identifier used by POST /robots/v1/jobs/summarize. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` SummarizeDirectiveBindingParameters: Parameters for summarize, excluding engine-supplied asset_id and source track_id where applicable. - `tone` 'neutral' | 'playful' | 'professional': Tone for the generated summary. "neutral" for straightforward analysis, "playful" for witty and conversational, "professional" for executive-level reporting. - `output_steering` SummarizeOutputSteering: Curated output_steering controls for execution scope, summary style, audience, brand terminology, and tag taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output. - … - `title_length` integer: Maximum title length in words. - `description_length` integer: Maximum description length in words. - `tag_count` integer: Maximum number of tags to include in the generated output. Defaults to 10. - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `output_language_code` string: BCP 47 language code for the generated summary output (e.g. "en", "fr", "ja"). Auto-detected from the transcript if omitted. - `update_asset_meta` boolean: When true, the generated title is written to the Mux asset's metadata (asset.meta.title) once the summary completes. Best-effort: a metadata-write failure does not fail the summary. - ModerateDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'moderate', required: Workflow identifier used by POST /robots/v1/jobs/moderate. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` ModerateDirectiveBindingParameters: Parameters for moderate, excluding engine-supplied asset_id and source track_id where applicable. - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `thresholds` object: Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}. - … - `sampling_interval` integer: Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints. - `max_samples` integer: Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned. - `output_steering` ModerateOutputSteering: Curated controls that optionally restrict moderation to an asset time range. - … - `on_flagged` ActionOnFlagged: Optional action taken automatically when exceeds_threshold is true. When omitted, the job only reports scores and takes no action. Note: in a directive run that targets the same asset with other workflows, deleting playback IDs can break sibling workflows that need a playback ID. - … - `include_transcript` boolean: Whether to moderate the asset's caption transcript in addition to sampled thumbnails. Applies to video assets with a ready caption track; audio-only assets are always moderated on their transcript. Set to false to moderate thumbnails only. - GenerateChaptersDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'generate-chapters', required: Workflow identifier used by POST /robots/v1/jobs/generate-chapters. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` GenerateChaptersDirectiveBindingParameters: Parameters for generate-chapters, excluding engine-supplied asset_id and source track_id where applicable. - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `output_language_code` string: BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted. - `output_steering` GenerateChaptersOutputSteering: Curated output_steering controls for chapter style, granularity, audience, and brand terminology. These controls guide model behavior but do not guarantee exact output. - … - `update_asset_chapters` boolean: When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_updates.chapters` in the job outputs for the outcome. - GenerateContextualTextDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'generate-contextual-text', required: Workflow identifier used by POST /robots/v1/jobs/generate-contextual-text. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` GenerateContextualTextDirectiveBindingParameters, required: Parameters for generate-contextual-text, excluding engine-supplied asset_id and source track_id where applicable. - `use_shots` boolean: When true for a video asset, generate or reuse Mux shots and attach a bounded sample of shot frames as additional visual evidence. Video assets always include a storyboard; the transcript remains authoritative. Not supported for audio-only assets. - `output_steering` GenerateContextualTextOutputSteering: Curated controls that apply to every generated artifact in every variant. Scope bounds execution; the other fields are best-effort writing guidance. To vary voice or audience between variants, use variant instructions. - … - `variants` GenerateContextualTextVariant[], required: Named versions of the complete artifact set. Every variant produces every artifact. Supports 1-5 variants with unique keys. - … - `artifacts` GenerateContextualTextArtifact[], required: The deliverables to create. Every variant produces each artifact. Supports 1-5 artifacts with unique keys. - … - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `output_language_code` string: BCP 47 language code for generated text. Defaults to the selected transcript track's language when available. - EditCaptionsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'edit-captions', required: Workflow identifier used by POST /robots/v1/jobs/edit-captions. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` EditCaptionsDirectiveBindingParameters: Parameters for edit-captions, excluding engine-supplied asset_id and source track_id where applicable. The engine selects the first ready subtitle in asset track order, or the single ready legacy text transcript on an audio-only asset. - `auto_censor_profanity` object: Optional LLM-driven profanity detection and censorship rules applied to the selected caption track. - … - `replacements` object[]: Optional static word or phrase replacements applied directly to cue text. - … - `speaker_replacements` EditCaptionsSpeakerReplacement[]: Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed. - … - `upload_to_mux` boolean: Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true. - `replace_existing_tracks` 'replace' | 'fail': What to do with the source track. Defaults to `replace`: the source is deleted and the edited track takes its place under the same name, language and closed-captions setting; no other track is touched, and the source is restored if the edited track can't be added. `fail` deletes nothing and adds the edited track alongside the source, so it requires a `track_name` different from the source's. Either way the request is rejected if a track other than the source already has the edited track's name. `replace` requires `upload_to_mux` to be true. - `track_name` string: Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset. - TranslateCaptionsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'translate-captions', required: Workflow identifier used by POST /robots/v1/jobs/translate-captions. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` TranslateCaptionsDirectiveBindingParameters, required: Parameters for translate-captions, excluding engine-supplied asset_id and source track_id where applicable. The engine selects the first eligible ready subtitle in asset track order, or the single ready legacy text transcript on an audio-only asset, whose language differs from output_language_code. Target-language comparison ignores case and region subtags, matching the track replacement rules. - `track_name` string: Name for the translated Mux text track. Defaults to "{Language} (Auto-translated)", e.g. "Spanish (Auto-translated)". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`. - `upload_to_mux` boolean: Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true. - `never_translate` string[]: Best-effort list of terms (brand names, proper nouns) to preserve verbatim in the translated captions. Does not guarantee exact output. Terms must not contain '<' or '>', invisible characters, or characters altered by Unicode normalization. - `replace_existing_tracks` 'fail' | 'replace_all' | 'replace_generated': What to do when the asset already has a text track in the same language as, or with the same name as, the translated track. Defaults to `fail`, which rejects the request before any translation is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status. - `output_language_code` string, required: BCP 47 language code for the translated output (e.g. "es", "ja"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language. - TranslateAudioDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'translate-audio', required: Workflow identifier used by POST /robots/v1/jobs/translate-audio. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` TranslateAudioDirectiveBindingParameters, required: Parameters for translate-audio, excluding engine-supplied asset_id and source track_id where applicable. - `track_name` string: Name for the dubbed Mux audio track. Defaults to "{Language} (Auto-dubbed)", e.g. "Spanish (Auto-dubbed)". Mux requires audio track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`. - `upload_to_mux` boolean: Whether to automatically upload the translated audio track to the Mux asset. Defaults to true. Must be false for audio-only assets; the job returns downloadable audio instead. - `replace_existing_tracks` 'fail' | 'replace_all' | 'replace_generated': What to do when the asset already has an audio track in the same language as, or with the same name as, the new dubbed track. Defaults to `fail`, which rejects the request before any dubbing is billed. `replace_all` deletes every such track first. Audio tracks are never auto-generated by Mux Video, so `replace_generated` behaves as `fail` here. The asset's primary audio track is never deleted. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status. - `output_language_code` string, required: BCP 47 language tag for the target audio (e.g. "es", "ur", "yue"). See [supported languages](https://www.mux.com/docs/guides/robots-supported-languages#translate-audio). Known ISO 639-3 aliases are accepted. Region and script subtags are retained on Mux tracks, but dubbing uses the base language. - AskQuestionsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'ask-questions', required: Workflow identifier used by POST /robots/v1/jobs/ask-questions. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` AskQuestionsDirectiveBindingParameters, required: Parameters for ask-questions, excluding engine-supplied asset_id and source track_id where applicable. - `questions` object[], required: One or more questions to ask about the video, up to 50. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer. - … - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript. - `max_free_form_answer_length` integer: Max character length for free-form answers, between 1 and 1000. Ignored unless at least one question sets free_form_reply: true. - `output_steering` AskQuestionsOutputSteering: Curated controls that optionally restrict question answering to an asset time range. - … - FindKeyMomentsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'find-key-moments', required: Workflow identifier used by POST /robots/v1/jobs/find-key-moments. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` FindKeyMomentsDirectiveBindingParameters: Parameters for find-key-moments, excluding engine-supplied asset_id and source track_id where applicable. - `max_moments` integer: Maximum number of key moments to extract. When omitted, defaults to 10 for assets up to one hour and 25 for longer assets. - `use_shots` boolean: Controls whether video assets are analyzed using Mux shots. When true, shots are generated or reused and visual evidence drives selection. When false or omitted, selection uses transcript evidence and the asset must have a caption track. Not supported for audio-only assets. - `output_steering` FindKeyMomentsOutputSteering: Curated output_steering controls for execution scope, selection strategy, title style, audience, taxonomy, and rubric tie-breakers. Scope is enforced; other controls guide model behavior but do not guarantee exact output. - … - `target_duration` FindKeyMomentsTargetDuration: Preferred highlight duration range in seconds. Best-effort guidance, with millisecond precision. - … - GenerateEngagementInsightsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'generate-engagement-insights', required: Workflow identifier used by POST /robots/v1/jobs/generate-engagement-insights. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` GenerateEngagementInsightsDirectiveBindingParameters: Parameters for generate-engagement-insights, excluding engine-supplied asset_id and source track_id where applicable. - GeneratePremiumCaptionsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'generate-premium-captions', required: Workflow identifier used by POST /robots/v1/jobs/generate-premium-captions. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` GeneratePremiumCaptionsDirectiveBindingParameters: Parameters for generate-premium-captions, excluding engine-supplied asset_id and source track_id where applicable. - `language_code` string: BCP 47 language code of the audio (e.g. "en", "es"). A best-effort hint that biases transcription toward this language — it is not verified against the audio and does not guarantee the output language. When supplied, language detection is skipped and the captions are labeled with this code. The language will be auto-detected when omitted; existing tracks are then checked against `replace_existing_tracks` after transcription, so a same-language conflict errors the job at track creation instead of being rejected up front, and a deleting policy only applies when the detection is confident. - `replace_existing_tracks` 'fail' | 'replace_all' | 'replace_generated': What to do when the asset already has a text track in the same language as, or with the same name as, the new caption track. Defaults to `fail`, which rejects the request before any work is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status. When `language_code` is omitted the detected language is used, and tracks are only deleted when the detection is confident; otherwise the job behaves as `fail`. - `track_name` string: Custom name for the uploaded Mux text track. Defaults to "{Language} (Generated)", e.g. "English (Generated)". Mux requires text track names to be unique on an asset. - `include_speakers` boolean: When true, speaker labels are identified and added to each caption cue. Useful for interviews, podcasts, and multi-speaker content. - `include_words` boolean: When true, word-level timestamps are exported as a JSON file accessible via temporary_words_url in the job outputs. The URL expires 7 days after the job completes. Billed at a higher unit rate. - `upload_to_mux` boolean: Whether to upload the generated SRT to the Mux asset as a new text track. Defaults to true. When false, no track is created and `replace_existing_tracks` must be `fail`; the generated SRT remains available via `temporary_srt_url`. - `phrases` string[]: Best-effort list of words or short phrases (proper nouns, product names, jargon) likely to appear in the audio, used to bias recognition toward correct spellings. Does not guarantee exact output. Each phrase may contain at most 49 characters and 5 words, and must not contain the characters <, >, {, }, [, ], or \. - FindBestThumbnailsDirectiveBinding - `reference_id` string, required: Binding identifier, unique within the directive. Producer references point to this identifier. - `workflow` 'find-best-thumbnails', required: Workflow identifier used by POST /robots/v1/jobs/find-best-thumbnails. - `inputs` string[]: Resource reference IDs that must become ready before dispatch. - `parameters` FindBestThumbnailsDirectiveBindingParameters: Parameters for find-best-thumbnails, excluding engine-supplied asset_id and source track_id where applicable. - `max_thumbnails` integer: Maximum number of candidate thumbnails to return (1-5). Defaults to 5. - `output_steering` FindBestThumbnailsOutputSteering: Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output. - … - `update_asset_thumbnail` boolean: When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings. - `id` string, required: Opaque directive identifier (drv_...). - `_links` DirectiveLinks, required - `self` DirectiveSelfLink, required - `href` string, required: URL to the directive in its creation API version. - `created_at` integer, required: Creation Unix timestamp in seconds. - `updated_at` integer, required: Last update Unix timestamp in seconds. ## Other responses - `401`: Missing or invalid Mux credentials - `403`: The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. For insufficient_scope, use credentials with the required permission. If using an API access token, create a replacement token with that permission. Enabling Robots for an organization does not grant token permissions. - `404`: Directive not found - `422`: Invalid request parameters - `500`: Server error ## Changes - **2026-11-03** `c0880e92f3ea`: 1 info - added the optional property `data/allOf[#/components/schemas/DirectiveConfig]/bindings/items/oneOf[#/components/schemas/ModerateDirectiveBinding]/parameters/include_transcript` to the response with the `200` status - **2026-10-23** `ed6cb570d60c`: 1 info - endpoint added [Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v1/directives/:DIRECTIVE_ID/get.md) --- [API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)