> For the complete documentation index, see [llms.txt](https://docs.wellcomecollection.org/request-for-comments-rfcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wellcomecollection.org/request-for-comments-rfcs/023-images-endpoint.md).

# RFC 023: Images endpoint

## Purpose

This RFC proposes an initial images endpoint for the catalogue API, allowing for searching and fetching images from the visual collections.

**Last modified:** 2020-05-06T14:53:14+00:00

## Context and requirements

* There is a new entity in the catalogue API: `Image`. These are conceptual, like works, and consist of images from the visual collections and interesting images from inside books and other materials.
* We want to be able to search for images, and to fetch specified images.
* The images endpoint should be consistent with the works endpoint.

## Proposal

The initial images endpoint will be in **beta**, and therefore will be liable to have breaking changes made without a version bump.

### Image display model

```
{
  "id": String,
  "locations": List[DigitalLocation],
  "source": {
    "id": String,
    "type": "Work"
  },
  "type": "Image"
}
```

This is intentionally minimal at this point as we decide what fields an image should have; it's what is needed to render the panel on search results.

### Single image

**`GET`** `/catalogue/v2/images/:image_id`

*Query params*

* `include` - optional list of fields, as with works endpoint
  * `visuallySimilar` - includes a list of visually similar works

### Multiple images

**`GET`** `/catalogue/v2/images`

*Query params*

* `query` - text search query
* `include` - optional list of extra fields *not including `visuallySimilar`*
* `locations.license` - license to filter for
* `page`
* `pageSize`