# Vocabulary API

The Vocabulary API manages the words your organization wants transcripts to get right: product names, people, places and jargon. Words live as entries, either private to one person or in a vocabulary list that can be shared.

## Key concepts

- **Private entries** — Words only their owner's transcripts use. Create one with `list_id` set to null.
- **Organization list** — Every organization has one list that every member reads. It cannot be deleted.
- **Custom lists** — Lists a person creates and owns, optionally in a team space. Share a custom list with people, teams, departments or the whole organization by creating an access grant on it.
- **Rights** — Every list and entry in a response says what the caller may do with it (`can_edit`, `can_share`, `can_delete`). A list or entry the caller cannot read answers 404; one they can read but not change answers 403.
- **Suggestions** — Words proposed for the shared vocabulary: members' names, assistant and project names, and words several colleagues learned from their own corrections. People who manage the team vocabulary approve or dismiss them.
- **Settings** — Organization-wide switches for learning from corrections and sharing learned words. Every member may read them; only people who manage the team vocabulary may change them, and every change names the `revision` it was based on.


## Quickstart

Create a list and add a word to it:


```bash
curl -X POST "https://api.aitronos.com/v1/vocabulary/lists" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product names"}'

curl -X POST "https://api.aitronos.com/v1/vocabulary/entries" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id": "voclist_8f2a61c4e0b94d7a", "written": "Kubernetes", "sounds_like": ["cube ernetes"]}'
```

## Endpoints

| Endpoint | Description |
|  --- | --- |
| [List vocabulary lists](/api-reference/vocabulary/list-vocabulary-lists) | Every list the caller can read, the organization list first |
| [Create a vocabulary list](/api-reference/vocabulary/create-a-vocabulary-list) | Create a custom list |
| [Get a vocabulary list](/api-reference/vocabulary/get-a-vocabulary-list) | One list the caller can read |
| [Update a vocabulary list](/api-reference/vocabulary/update-a-vocabulary-list) | Rename, describe, switch off or move a list |
| [Delete a vocabulary list](/api-reference/vocabulary/delete-a-vocabulary-list) | Delete a custom list and its entries |
| [List vocabulary entries](/api-reference/vocabulary/list-vocabulary-entries) | Page private, list or shared entries |
| [Create a vocabulary entry](/api-reference/vocabulary/create-a-vocabulary-entry) | Add a private entry or an entry to a list |
| [Get a vocabulary entry](/api-reference/vocabulary/get-a-vocabulary-entry) | One entry the caller can read |
| [Update a vocabulary entry](/api-reference/vocabulary/update-a-vocabulary-entry) | Change an entry |
| [Delete a vocabulary entry](/api-reference/vocabulary/delete-a-vocabulary-entry) | Delete an entry |
| [Undo a learned vocabulary entry](/api-reference/vocabulary/undo-a-learned-vocabulary-entry) | Remove a word learned from a correction |
| [Import words into a vocabulary list](/api-reference/vocabulary/import-words-into-a-vocabulary-list) | Add and update words from an `.xlsx` or `.csv` file |
| [Export a vocabulary list](/api-reference/vocabulary/export-a-vocabulary-list) | Download a list as `.xlsx` or `.csv` |
| [Preview vocabulary](/api-reference/vocabulary/preview-vocabulary) | Which words a call would use, and what each model keeps |
| [List vocabulary suggestions](/api-reference/vocabulary/list-vocabulary-suggestions) | Words proposed for the organization's vocabulary |
| [Refresh vocabulary suggestions](/api-reference/vocabulary/refresh-vocabulary-suggestions) | Collect new suggestions now |
| [Approve a vocabulary suggestion](/api-reference/vocabulary/approve-a-vocabulary-suggestion) | Write a suggested word into a list |
| [Dismiss a vocabulary suggestion](/api-reference/vocabulary/dismiss-a-vocabulary-suggestion) | Never suggest a word again |
| [Approve or dismiss vocabulary suggestions in bulk](/api-reference/vocabulary/approve-or-dismiss-vocabulary-suggestions-in-bulk) | Decide up to 100 suggestions at once |
| [Get vocabulary settings](/api-reference/vocabulary/get-vocabulary-settings) | Read the organization's vocabulary settings |
| [Update vocabulary settings](/api-reference/vocabulary/update-vocabulary-settings) | Change the organization's vocabulary settings |


## Related Resources

- [Create an access grant](/api-reference/access-control/create-grant) — Share a vocabulary list.