# Refresh vocabulary suggestions

Collect new suggestions now instead of waiting for the daily refresh. A refresh writes at most 1,000 suggestions; when it stops early `budget_exhausted` is true and another refresh continues. A suggestion that was already approved or dismissed is never reopened. Needs the right to manage the team vocabulary.

## Returns

**`created`** integer

New suggestions.

**`updated`** integer

Pending suggestions brought up to date.

**`by_source`** object

Suggestions created or updated, per source (`people`, `assistant`, `project`, `learned`).

**`refreshed_at`** string

When the refresh ran.

**`budget_exhausted`** boolean

True when the refresh stopped at its write limit; refresh again to continue.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/vocabulary/suggestions/refresh" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/vocabulary/suggestions/refresh",
    headers={"X-API-Key": api_key},
)

print(response.json())
```


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

const response = await fetch('https://api.aitronos.com/v1/vocabulary/suggestions/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  }
});

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

**Response:**


```json 200 OK
{
  "created": 12,
  "updated": 2,
  "by_source": {
    "people": 9,
    "assistant": 1,
    "project": 2,
    "learned": 2
  },
  "refreshed_at": "2026-10-26T09:30:00Z",
  "budget_exhausted": false
}
```

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

## Related Resources

- [List vocabulary suggestions](/api-reference/vocabulary/list-vocabulary-suggestions) — Read what the refresh found.
- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.