1. Executive Summary
Voice configurations provisioned through the watsonx Orchestrate UI using the IBM-provided OEM Deepgram integration cannot be exported and re-imported via the ADK CLI. Two distinct 422 errors are encountered depending on the approach taken, effectively making voice configuration a UI-only operation in this environment. This is a significant blocker for any team following a pro-code, Infrastructure-as-Code, or CI/CD deployment model.
2. Environment & Context
ADK CLI: ibm-watsonx-orchestrate (venv), ibm_iam auth
STT: deepgram_stt / model flux-general-en / endpoint wss://api.eu.deepgram.com/v2/listen
TTS: deepgram_tts / model flux-sharon-en / endpoint https://api.eu.deepgram.com
Key type: IBM OEM Deepgram key — provisioned automatically by WXO when voice config is created in the UI
3. Steps to Reproduce
Step 1 — Export the voice configuration:
orchestrate voice-configs export --id <ID_name> --output voice\exported_voice_configuration.yaml
✓ Export succeeds. WXO correctly notes: "Sensitive fields, such as API keys, have been removed."
The exported YAML is structurally valid but contains no api_key fields.
Step 2a — Attempt to re-import the original exported file (same name):
orchestrate voice-configs import --file exported_voice_configuration.yaml
Error — 422 Unprocessable Entity (PATCH)
ClientAPIException(status_code=422, message={"detail":"Usage of the OEM keys is internally restricted."})
Because the file name matches an existing config, the CLI routes to a PATCH request on the existing UUID. The server then rejects the update because the config is backed by an OEM key.
Step 2b — Attempt to import with a renamed file (new config):
orchestrate voice-configs import --file pa_voice_config_en.yaml
# (same YAML content, only name field changed to 'pa_voice_config_en')
Error — 422 Unprocessable Entity (POST)
ClientAPIException(status_code=422, message={"detail":[
{"type":"missing","loc":["body","speech_to_text","deepgram_stt_config","api_key"],"msg":"Field required"},
{"type":"missing","loc":["body","text_to_speech","deepgram_tts_config","api_key"],"msg":"Field required"}
]})
The rename correctly triggers a POST (new config, no OEM restriction). However, because the ADK CLI export strips the api_key fields — as documented — and those fields are marked required by the API schema, the import fails. There is no mechanism to supply the OEM key value because it is not exposed to users.
4. Reproduction Matrix
Approach HTTP method Result Root cause
Import same-name exported file PATCH 422 — OEM key restricted Update of OEM-keyed config blocked server-side
Import renamed file (new config) POST 422 — api_key required Export strips key; API schema marks it required; OEM key value not user-accessible
Create voice config via WXO UI UI Works UI injects OEM key server-side without exposing it
5. Business Impact
Pro-code deployments blocked: Any team managing WXO resources through YAML files, Git, or CI/CD pipelines cannot include voice configurations in their deployment automation.
Multi-environment promotion impossible: Voice configs cannot be promoted from dev → staging → production via the CLI. Each environment requires manual UI intervention.
Export/import parity broken: The ADK CLI advertises voice-configs export and voice-configs import as a round-trip capability. For OEM-keyed Deepgram configs, this round-trip does not function.
Documentation gap: ADK documentation does not warn that OEM-provisioned voice configurations are exempt from CLI import/update operations.
Workspace migration blocked: Resources cannot be moved between workspaces programmatically if they include OEM voice configs.
6. Root Cause Analysis
The issue stems from a design conflict between three independently correct behaviours that are incompatible when combined:
Security correct: OEM API keys are not exposed to end users — this is intentional and appropriate.
Security correct: The export command strips sensitive fields (api_key) before writing to disk — this is intentional and appropriate.
API correct: The voice config create/update API requires api_key as a mandatory field — this is schema-correct.
The result is a closed loop: the user cannot provide the OEM key (rule 1), the export removes it (rule 2), and the import requires it (rule 3). No CLI path can satisfy all three constraints simultaneously.
7. Requested Actions for IBM watsonx Orchestrate (product & engineering):
Option A — OEM key passthrough on import: When importing a voice config that references a Deepgram OEM integration (no api_key in the file and environment is OEM-enabled), automatically inject the OEM key server-side rather than rejecting the request. The UI already does this; the import path should have parity.
Option B — Allow update of OEM-keyed configs via CLI: Remove or scope the "Usage of the OEM keys is internally restricted" restriction so that PATCH operations on OEM-keyed voice configs are permitted when the update does not modify the key itself.
Documentation fix (immediate): Add a note to the voice-configs import and voice-configs export ADK documentation pages stating that OEM-provisioned Deepgram voice configurations cannot currently be re-imported via CLI and require a user-supplied Deepgram API key for pro-code deployments.
ADK warning improvement: The CLI currently warns that flux-general-en is "not officially supported" but does not warn about the OEM key restriction. Add an explicit warning when importing a file that has no api_key and would target an OEM-backed config.
OEM key scoping: The OEM Deepgram key provisioned by WXO is currently scoped in a way that prevents programmatic re-use outside the UI flow. A mechanism to allow server-side key injection for trusted platform integrations (without exposing key values to end users) would resolve the blocker above.
