Speech

About 584 wordsAbout 2 min

Generated from docs/.vuepress/openapi.json. Refresh with npm run gen:api. Back to overview.

`GET /api/v1/speech/capability` — Speech-to-text provider capability

Tags: Speech

Query parameters

Name	Type	Required	Description
`agent_id`	integer	no	Scope the cascade to this agent’s principal (user or group). Omit for caller-scoped (composer).

Responses

Status	Description
`200`	Capability summary

`GET /api/v1/speech/preference` — Read the caller’s preferred speech-to-text provider

Tags: Speech

Query parameters

Name	Type	Required	Description
`scope`	string	yes
`group_id`	integer	no

Responses

Status	Description
`200`	Current preference row
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`422`	SPEECH_PROVIDER_CONFIG_INVALID

`PUT /api/v1/speech/preference` — Set or clear the caller’s preferred speech-to-text configuration

Tags: Speech

Request body

application/json — required

Field	Type	Required	Description
`config_id`	integer \| null	yes
`scope`	string	yes	One of `user`, `group`.
`group_id`	integer \| null	no

Responses

Status	Description
`200`	Updated preference row
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`422`	SPEECH_PROVIDER_CONFIG_INVALID

`GET /api/v1/speech/provider-configs` — List speech provider configurations visible to the caller

Tags: Speech

Query parameters

Name	Type	Required	Description
`group_id`	integer	no	When set, returns the speech provider configs attached to that group. The caller must be a member of the group or a global admin; non-members receive an empty list.
`agent_id`	integer	no	When set, returns only the configs valid for that agent’s principal scope (configs scoped to the agent’s owning principal, plus every global config). Use this on the agent-settings page so a user-owned agent does not surface configs owned by groups the caller happens to belong to.

Responses

Status	Description
`200`	Configs

`POST /api/v1/speech/provider-configs` — Create a speech provider configuration

Tags: Speech

Request body

application/json — required

Field	Type	Required	Description
`provider_class`	string	yes
`display_name`	string	no
`is_global`	boolean	no	Admin-only. When true, the row is the global config; principal_id will be null.
`principal_id`	integer \| null	no	When set, the config is scoped to this principal (user or group). Caller must control the principal.
`scope`	string	no	One of `user`, `group`, `global`, `agent`.
`group_id`	integer	no
`settings`	object	yes

Responses

Status	Description
`201`	Created config
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`404`	SPEECH_PROVIDER_CONFIG_NOT_FOUND
`422`	SPEECH_PROVIDER_CONFIG_INVALID

`PUT /api/v1/speech/provider-configs/{id}` — Update an existing speech provider configuration

Tags: Speech

Path parameters

Name	Type	Required	Description
`id`	integer	yes
`id`	integer	yes

Request body

application/json — required

Field	Type	Required	Description
`display_name`	string	no
`settings`	object	no

Responses

Status	Description
`200`	Updated config
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`404`	SPEECH_PROVIDER_CONFIG_NOT_FOUND
`422`	SPEECH_PROVIDER_CONFIG_INVALID

`DELETE /api/v1/speech/provider-configs/{id}` — Delete a speech provider configuration

Tags: Speech

Path parameters

Name	Type	Required	Description
`id`	integer	yes
`id`	integer	yes

Responses

Status	Description
`200`	Deleted
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`404`	SPEECH_PROVIDER_CONFIG_NOT_FOUND

`POST /api/v1/speech/provider-configs/{id}/set-default` — Mark a global speech provider configuration as default

Tags: Speech

Path parameters

Name	Type	Required	Description
`id`	integer	yes
`id`	integer	yes

Responses

Status	Description
`200`	Updated config (with is_default=true)
`403`	SPEECH_PROVIDER_CONFIG_FORBIDDEN
`404`	SPEECH_PROVIDER_CONFIG_NOT_FOUND

`GET /api/v1/speech/provider-configs/schema` — Registered speech-to-text provider classes with their settings schemas

Tags: Speech

Responses

Status	Description
`200`	Provider schemas

`POST /api/v1/speech/transcribe` — Transcribe a recorded audio asset

Tags: Speech

Request body

application/json — required

Field	Type	Required	Description
`media_id`	string (uuid)	yes
`language`	string \| null	no	BCP-47 hint (e.g. “en-US”). null = auto-detect.
`agent_id`	integer \| null	no	Optional agent id (must be owned by the caller). Accepted for backwards compatibility — the controller validates ownership but the speech cascade no longer threads agent_id into settings lookup, so per-agent STT overrides are out of scope.

Responses

Status	Description
`200`	Transcript
`404`	MEDIA_NOT_FOUND
`422`	INVALID_AUDIO or validation error
`502`	SPEECH_PROVIDER_FAILED
`503`	SPEECH_PROVIDER_UNAVAILABLE