# Create a vocabulary entry

Create a private entry (`list_id` null) or an entry in a list the caller may add to. A word already in the same place, in the same language, answers 409.

#### Request Body

**`list_id`** string optional

The list to add the entry to; null creates a private entry.

**`written`** string required

How the word is written, 1 to 100 characters.

**`sounds_like`** array of string optional

Up to 10 ways the word may be spoken or misheard.

**`language`** string optional

A language tag such as `de` or `de-CH`; null for all languages.

**`kind`** string optional · Defaults to `bias`

`bias` or `replace`.

**`weight`** number optional · Defaults to `1.0`

How strongly the word is favoured, above 0 and up to 10.

**`enabled`** boolean optional · Defaults to `true`

Whether the entry is used in transcripts.

**`visibility`** string optional

For an entry in a list: `list` (the default) or `restricted`. Not allowed on a private entry.

## Returns

The new vocabulary entry:

**`id`** string

The entry ID: `pdict_…` for a private entry, `tdict_…` for one in a list.

**`scope`** string

`personal` for a private entry, `list` for an entry in a list.

**`list_id`** string or null

The list the entry belongs to, if any.

**`written`** string

How the word is written.

**`sounds_like`** array of string

How the word may be spoken or misheard.

**`language`** string or null

The language tag; null for all languages.

**`kind`** string

`bias` makes the word more likely to be recognised; `replace` also rewrites the spoken forms to the written form.

**`source`** string

How the entry was created.

**`weight`** number

How strongly the word is favoured, above 0 and up to 10.

**`enabled`** boolean

Whether the entry is used in transcripts.

**`visibility`** string

`private` for a private entry; `list` when everyone who reads the list sees it; `restricted` when only the people it is shared with see it.

**`shared`** boolean

Whether the entry is shared on its own.

**`owner_user_id`** string

The person who created the entry.

**`reached_through`** string

How the entry reached the caller.

**`can_edit`** boolean

Whether the caller may change the entry.

**`can_share`** boolean

Whether the caller may share the entry.

**`stats`** object

Usage counters: `applied_count`, `heard_count`, `corrected_count`, `last_applied_at`, `last_heard_at`.

**`created_at`** string

When the entry was created.

**`updated_at`** string

When the entry last changed.

Example

```bash cURL
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", "kuber netties"]}'
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/vocabulary/entries",
    headers={"X-API-Key": api_key},
    json={"list_id": "voclist_8f2a61c4e0b94d7a", "written": "Kubernetes", "sounds_like": ["cube ernetes", "kuber netties"]},
)

print(response.json())
```


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

const response = await fetch('https://api.aitronos.com/v1/vocabulary/entries', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"list_id": "voclist_8f2a61c4e0b94d7a", "written": "Kubernetes", "sounds_like": ["cube ernetes", "kuber netties"]})
});

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

**Response:**


```json 201 Created
{
  "id": "tdict_5a9c2e7b1d3f4068",
  "scope": "list",
  "list_id": "voclist_8f2a61c4e0b94d7a",
  "written": "Kubernetes",
  "sounds_like": [
    "cube ernetes",
    "kuber netties"
  ],
  "language": null,
  "kind": "bias",
  "source": "manual",
  "weight": 1.0,
  "enabled": true,
  "visibility": "list",
  "shared": false,
  "owner_user_id": "usr_3c91d0a2b7e4",
  "reached_through": "owner",
  "can_edit": true,
  "can_share": true,
  "stats": {
    "applied_count": 14,
    "heard_count": 9,
    "corrected_count": 0,
    "last_applied_at": "2026-10-24T09:30:00Z",
    "last_heard_at": "2026-10-24T09:30:00Z"
  },
  "created_at": "2026-10-24T09:30:00Z",
  "updated_at": "2026-10-24T09:30:00Z"
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```


```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-24T09:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "VOCABULARY_LIST_NOT_FOUND",
    "message": "This vocabulary list does not exist or you cannot see it.",
    "system_message": "Vocabulary list not found.",
    "type": "client_error",
    "status": 404,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "DICTIONARY_TERM_DUPLICATE",
    "message": "This word is already in this vocabulary.",
    "system_message": "Duplicate term in the same place and language.",
    "type": "client_error",
    "status": 409,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```

## Related Resources

- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.
- [Create an access grant](/api-reference/access-control/create-grant) — Share a vocabulary list with people, teams or the whole organization.