---
method: GET
path: /api/media-items/facets
auth: jwt
area: media-items
---
<!-- source: internal/handlers/media.go:2532 MediaHandler.GetFacets -->

# Get Media Item Facets

Two modes, both returning small JSON objects:

1. **Facet values** (primary): `?facet=<param>&library_id=<uuid>` — lists the
   distinct values of a facet within one visible library.
2. **Autocomplete counts**: `?field=<key>&library_id=<uuid>` — returns
   `{"facets": {...}}` value counts for dropdowns.

## Example response

```json example-response
{
  "facet": "author",
  "values": [
    {
      "value": "George Orwell"
    }
  ]
}
```

`values` elements are `{value, display?, count}` rows (`FacetValue`):
`value` is the raw value that rides the filter param, `display` is the
prettified form when it differs (language codes → names; absent means the
client shows `value`), `count` is the number of matching items.

## Query parameters

| Param | Type | Notes |
| ----- | ---- | ----- |
| facet | string | facet param name; requires `library_id` |
| field | string | registry field key (autocomplete mode) |
| library_id | uuid | required for facet mode; must be visible to the requester |
| limit | number | caps facet values |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "library_id is required"}` / `{"error": "unknown facet: ..."}` / `{"error": "facet does not list values: ..."}` / `{"error": "invalid library_id"}` | bad params |
| 403 | `{"error": "library not visible"}` | family lens |
| 500 | `{"error": "..."}` | unexpected server error |