# Preview vocabulary

Which of the caller's own words a call would use, and what each transcription model keeps of them. Nothing is transcribed and nothing is sent.

#### Request Body

**`use_case`** string optional · Defaults to `dictation`

The kind of call to preview: `dictation`, `voice_agent`, `meeting_live`, `meeting_record`, `meeting_upload` or `knowledge_media`.

**`models`** array of string optional

Up to 10 transcription model keys to compare. Empty previews the model this kind of call uses.

**`mode`** string optional · Defaults to `stream`

`stream` (live) or `batch` (file).

**`language`** string optional

The expected language, such as `de` or `de-CH`; null detects it.

**`app_key`** string optional

The app dictated into, when known. Words often used in that app weigh more.

**`attendee_emails`** array of string optional

Up to 200 meeting attendees. They add names and company names, never another person's words.

**`sample_text`** string optional

Up to 5,000 characters. Returns which words a cleanup step would consider for this text.

## Returns

The caller's selection and what each model keeps of it:

**`selection`** object

How many words the call would use: `status` (`selected`, `none_configured`, or `could_not_run` when the vocabulary could not be read and the call would go ahead without it), `selected_count`, `personal_count`, `shared_count`, `list_count`, `context_count` (attendee names, company names and the assistant's name) and `skipped_too_long_count` (words over 100 characters, never sent).

**`terms`** array of object

The words in relevance order, at most 1,000. Each has `written`, `entry_id` (null for a context word), `reached_through` (how the word reached the caller, or `context`), `kind`, `weight` (above 0 up to 10) and `language`.

**`replacements`** array of object

The words of kind `replace`, applied after recognition, in the same shape.

**`engines`** array of object

One per requested model, or one for the kind of call: `model`, `status` (`none_requested`, `applied`, `partially_applied`, `not_supported_in_mode` or `not_supported_by_model`), `requested_count`, `applied_count`, `trimmed_count`, `boost` (`weighted`, `priority_order` or `not_requested`), `applied` (the first 100 words used) and `first_trimmed` (the most relevant word that did not fit).

**`cleanup_entries`** array of object or null

The words a cleanup step would consider for `sample_text`; null without it.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/vocabulary/preview" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case": "dictation", "models": ["fvt-engine-01"], "mode": "batch"}'
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/vocabulary/preview",
    headers={"X-API-Key": api_key},
    json={"use_case": "dictation", "models": ["fvt-engine-01"], "mode": "batch"},
)

print(response.json())
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/vocabulary/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"use_case": "dictation", "models": ["fvt-engine-01"], "mode": "batch"})
});

const data = await response.json();
console.log(data);
```

**Response:**


```json 200 OK
{
  "selection": {
    "status": "selected",
    "selected_count": 2,
    "personal_count": 1,
    "shared_count": 0,
    "list_count": 1,
    "context_count": 0,
    "skipped_too_long_count": 0
  },
  "terms": [
    {
      "written": "Kubernetes",
      "entry_id": "pdict_4c1e9a7b2d5f4083",
      "reached_through": "owner",
      "kind": "bias",
      "weight": 10.0,
      "language": null
    },
    {
      "written": "Smart Documents",
      "entry_id": "tdict_8a3f6b1c9e2d4705",
      "reached_through": "organization",
      "kind": "replace",
      "weight": 7.69,
      "language": "en"
    }
  ],
  "replacements": [
    {
      "written": "Smart Documents",
      "entry_id": "tdict_8a3f6b1c9e2d4705",
      "reached_through": "organization",
      "kind": "replace",
      "weight": 7.69,
      "language": "en"
    }
  ],
  "engines": [
    {
      "model": "fvt-engine-01",
      "status": "applied",
      "requested_count": 2,
      "applied_count": 2,
      "trimmed_count": 0,
      "boost": "priority_order",
      "applied": ["Kubernetes", "Smart Documents"],
      "first_trimmed": null
    }
  ],
  "cleanup_entries": null
}
```

Errors

```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Caller lacks the rights this operation needs.",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-25T09:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "SPEECH_MODEL_NOT_FOUND",
    "message": "Unknown transcription model",
    "system_message": "Unknown transcription model",
    "type": "validation_error",
    "status": 422,
    "details": {
      "models": ["no-such-model"]
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-25T09:30:00Z"
  }
}
```


```json 503 Service Unavailable
{
  "success": false,
  "error": {
    "code": "ASR_UNAVAILABLE",
    "message": "The transcription engine for this preview is unavailable",
    "system_message": "The transcription engine for this preview is unavailable",
    "type": "service_unavailable",
    "status": 503,
    "details": {
      "model": "fvt-engine-01",
      "reason": "engine_unavailable",
      "retry_after": 2
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-25T09:30:00Z"
  }
}
```

## Related Resources

- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.
- [Create a vocabulary entry](/api-reference/vocabulary/create-a-vocabulary-entry) — Add a word to preview.