---
title: "Set stored Hear vocabulary"
method: PUT
path: "/v1/hear/vocabulary"
tags: ["Speech To Text (Hear)"]
---

# Set stored Hear vocabulary

`PUT /v1/hear/vocabulary`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/hear/vocabulary`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Replace the organization's stored custom vocabulary and activation profiles. PyAI keeps at most five sanitized terms. Stored terms bias known vocabulary only for the profiles named in `enabled_for`. Per-job or per-session vocabulary comes first, then stored suggestions fill remaining slots up to five. Requires the `hear:configure` scope.

## Request body

- HearVocabularyInput
  - `terms` string[], required: Organization-owned names, brands, products, and other distinctive terms. PyAI keeps the first five entries that pass the same sanitizer used by async jobs.
  - `enabled_for` string[], required: Explicit use cases that may use stored terms. An empty array stores the list without applying it.

## Response `200`

Updated Hear vocabulary settings

- HearVocabulary
  - `object` 'hear.vocabulary', required
  - `terms` string[], required: The sanitized effective stored list.
  - `enabled_for` string[], required
  - `updated_at` integer, nullable, required: Unix milliseconds, or null when no settings have been saved.

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `401`: Missing or invalid API key (`code: unauthorized`)
- `403`: Key lacks the required scope or the origin is not allow-listed (`code: forbidden | origin_not_allowed`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)