Summary

The v1.7.3 OpenAPI spec sync (#106) added target_mode_list to the ChannelTargetProperties enum — the field-name vocabulary backing the search_fields query param on GET /api/v1/channels/targets (CLI: channels targets list --search-field). The search_field_values param explicitly allows a comma-separated list when the field name contains list, so the intended usage is filtering channel targets by a list of modes (e.g. voice,sms).

The production API rejects it with 422. Prod's search_fields validation enum does not include target_mode_list.

Live repro (verified 2026-06-08 on cli-test, CLI v1.7.3)

$ syllable --org cli-test channels targets list --search-field target_mode_list --search "voice,sms" --debug
> GET https://api.syllable.cloud/api/v1/channels/targets?...&search_fields=target_mode_list&search_field_values=voice%2Csms
< 422 Unprocessable Entity
< {"detail":[{"type":"enum","loc":["query","search_fields",0],
<   "msg":"Input should be 'id', 'channel_id', 'channel_name', 'agent_id', 'target', 'target_mode', 'fallback_target', 'is_test', 'updated_at' or 'a2p_verified'",
<   "input":"target_mode_list"}]}

Control (same org, same empty target list) — the search mechanism itself works; only target_mode_list is rejected:

$ syllable --org cli-test channels targets list --search-field target_mode --search "voice" --debug   # 200 OK
$ syllable --org cli-test channels targets list --search-field target      --search "x"     --debug   # 200 OK
$ syllable --org cli-test channels targets list --search-field target_mode_list --search "voice,sms"  # 422

A 422 enum-validation error is returned before any data evaluation, so the empty cli-test target list does not affect the result.

Spec vs. prod

The prod enum currently matches ChannelTargetOrderProperties (the sortable subset), not the expanded filter enum.

Impact

channels targets list filtering by target mode list does not work against prod. order_by is not affected from the CLI (the targets list command exposes no --order-by flag, so ChannelTargetOrderProperties has no CLI surface).

Expected

Either the backend deploys target_mode_list support for search_fields, or the spec is corrected. Until then the CLI advertises a filter prod won't accept.

Same drift family as #100 (bridges messages/randomize_messages) — spec advertises a capability prod hasn't deployed. This one fails loud (422) rather than silently.

Documented in the ai-specialist syllable-cli skill references/gotchas.md (§ Channels).