{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Preview vocabulary","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"preview-vocabulary","__idx":0},"children":["Preview vocabulary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/vocabulary/preview"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body","__idx":1},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_case"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}," · Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dictation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The kind of call to preview: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dictation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voice_agent"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meeting_live"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meeting_record"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meeting_upload"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["knowledge_media"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["models"]}]}," array of string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Up to 10 transcription model keys to compare. Empty previews the model this kind of call uses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}," · Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stream"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stream"]}," (live) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch"]}," (file)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The expected language, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de-CH"]},"; null detects it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The app dictated into, when known. Words often used in that app weigh more."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attendee_emails"]}]}," array of string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Up to 200 meeting attendees. They add names and company names, never another person's words."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sample_text"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Up to 5,000 characters. Returns which words a cleanup step would consider for this text."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":2},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The caller's selection and what each model keeps of it:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selection"]}]}," object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How many words the call would use: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selected"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none_configured"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["could_not_run"]}," when the vocabulary could not be read and the call would go ahead without it), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selected_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["personal_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shared_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["context_count"]}," (attendee names, company names and the assistant's name) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skipped_too_long_count"]}," (words over 100 characters, never sent)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["terms"]}]}," array of object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The words in relevance order, at most 1,000. Each has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["written"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entry_id"]}," (null for a context word), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reached_through"]}," (how the word reached the caller, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["context"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["weight"]}," (above 0 up to 10) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replacements"]}]}," array of object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The words of kind ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replace"]},", applied after recognition, in the same shape."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["engines"]}]}," array of object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One per requested model, or one for the kind of call: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["model"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none_requested"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applied"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partially_applied"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_supported_in_mode"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_supported_by_model"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requested_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applied_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trimmed_count"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boost"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["weighted"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["priority_order"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_requested"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applied"]}," (the first 100 words used) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_trimmed"]}," (the most relevant word that did not fit)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cleanup_entries"]}]}," array of object or null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The words a cleanup step would consider for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sample_text"]},"; null without it."]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X POST \"https://api.aitronos.com/v1/vocabulary/preview\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"use_case\": \"dictation\", \"models\": [\"fvt-engine-01\"], \"mode\": \"batch\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import os\nimport requests\n\napi_key = os.environ[\"FREDDY_API_KEY\"]\n\nresponse = requests.post(\n    \"https://api.aitronos.com/v1/vocabulary/preview\",\n    headers={\"X-API-Key\": api_key},\n    json={\"use_case\": \"dictation\", \"models\": [\"fvt-engine-01\"], \"mode\": \"batch\"},\n)\n\nprint(response.json())\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const apiKey = process.env.FREDDY_API_KEY;\n\nconst response = await fetch('https://api.aitronos.com/v1/vocabulary/preview', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': apiKey,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\"use_case\": \"dictation\", \"models\": [\"fvt-engine-01\"], \"mode\": \"batch\"})\n});\n\nconst data = await response.json();\nconsole.log(data);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"200 OK","header":{"title":"200 OK","controls":{"copy":{}}},"source":"{\n  \"selection\": {\n    \"status\": \"selected\",\n    \"selected_count\": 2,\n    \"personal_count\": 1,\n    \"shared_count\": 0,\n    \"list_count\": 1,\n    \"context_count\": 0,\n    \"skipped_too_long_count\": 0\n  },\n  \"terms\": [\n    {\n      \"written\": \"Kubernetes\",\n      \"entry_id\": \"pdict_4c1e9a7b2d5f4083\",\n      \"reached_through\": \"owner\",\n      \"kind\": \"bias\",\n      \"weight\": 10.0,\n      \"language\": null\n    },\n    {\n      \"written\": \"Smart Documents\",\n      \"entry_id\": \"tdict_8a3f6b1c9e2d4705\",\n      \"reached_through\": \"organization\",\n      \"kind\": \"replace\",\n      \"weight\": 7.69,\n      \"language\": \"en\"\n    }\n  ],\n  \"replacements\": [\n    {\n      \"written\": \"Smart Documents\",\n      \"entry_id\": \"tdict_8a3f6b1c9e2d4705\",\n      \"reached_through\": \"organization\",\n      \"kind\": \"replace\",\n      \"weight\": 7.69,\n      \"language\": \"en\"\n    }\n  ],\n  \"engines\": [\n    {\n      \"model\": \"fvt-engine-01\",\n      \"status\": \"applied\",\n      \"requested_count\": 2,\n      \"applied_count\": 2,\n      \"trimmed_count\": 0,\n      \"boost\": \"priority_order\",\n      \"applied\": [\"Kubernetes\", \"Smart Documents\"],\n      \"first_trimmed\": null\n    }\n  ],\n  \"cleanup_entries\": null\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Errors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"403 Forbidden","header":{"title":"403 Forbidden","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_PERMISSIONS\",\n    \"message\": \"You do not have permission to perform this action.\",\n    \"system_message\": \"Caller lacks the rights this operation needs.\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {},\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-25T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"422 Unprocessable Entity","header":{"title":"422 Unprocessable Entity","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SPEECH_MODEL_NOT_FOUND\",\n    \"message\": \"Unknown transcription model\",\n    \"system_message\": \"Unknown transcription model\",\n    \"type\": \"validation_error\",\n    \"status\": 422,\n    \"details\": {\n      \"models\": [\"no-such-model\"]\n    },\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-25T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"503 Service Unavailable","header":{"title":"503 Service Unavailable","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ASR_UNAVAILABLE\",\n    \"message\": \"The transcription engine for this preview is unavailable\",\n    \"system_message\": \"The transcription engine for this preview is unavailable\",\n    \"type\": \"service_unavailable\",\n    \"status\": 503,\n    \"details\": {\n      \"model\": \"fvt-engine-01\",\n      \"reason\": \"engine_unavailable\",\n      \"retry_after\": 2\n    },\n    \"trace_id\": \"req_7d1e4b9a2c\",\n    \"timestamp\": \"2026-10-25T09:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":3},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/vocabulary/_index"},"children":["Vocabulary API"]}," — Overview of lists, entries and settings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/vocabulary/create-a-vocabulary-entry"},"children":["Create a vocabulary entry"]}," — Add a word to preview."]}]}]},"headings":[{"value":"Preview vocabulary","id":"preview-vocabulary","depth":1},{"value":"Request Body","id":"request-body","depth":4},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Preview vocabulary","keywords":["preview vocabulary","post","preview","vocabulary"],"seo":{"title":"Preview vocabulary"}},"lastModified":"2026-10-26T10:47:31.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/vocabulary/preview-vocabulary","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}