# RFC 023: Images endpoint

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-06T15:53:14+01: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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wellcomecollection.org/request-for-comments-rfcs/023-images-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.