---
title: "Find an image the site already holds"
method: GET
path: "/api/media/library"
tags: ["Proposing changes"]
---

# Find an image the site already holds

`GET /api/media/library`

## Request

- Base URL: `https://verifiedhandles.org`
- URL: `https://verifiedhandles.org/api/media/library`
- Auth: HTTP bearer

The image picker’s “On Verified Handles” tab: images the site holds that may go on an entry (never a withdrawn one), found by the entries that show or showed them, a file name, a credit or licence, or `#<id>`. 24 to a page, newest first. Each says its licence and credit and which entries use it; a deleted entry is never named. Fewer than 2 characters finds nothing. Counted against the same per-account limit as changes, 60 a minute.

## Query parameters

- `q` string, required
- `offset` integer

## Response `200`

A page of images.

- object
  - `query` string, required
  - `total` integer, required
  - `next_offset` integer, nullable, required
  - `results` LibraryImage[], required
    - `id` string, required: The image’s id: what a proposal names as `image_id`.
    - `kind` 'commons' | 'local', required: `commons`: a Wikimedia Commons file; `local`: an upload.
    - `filename` string, nullable, required: A Commons file’s name; null for an upload.
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `license` string, nullable, required: An upload’s licence id; null for a Commons file.
    - `license_name` string, nullable, required
    - `license_url` string, nullable, required
    - `credit` string, nullable, required
    - `commons_page` string, nullable, required
    - `used_by` object[], required: Entries showing it now.
      - `vhid` string, required
      - `short` string, nullable, required
      - `title` string, required
    - `used_before` object[], required: Entries that showed it before.
      - `vhid` string, required
      - `short` string, nullable, required
      - `title` string, required
    - `restricted` true: Present only to an account that may use restricted images.

## Other responses

- `400`: The text is over 200 characters (`query_too_long`). Or the request sent a key and a session cookie together (`bearer_with_cookie`): send one.
- `401`: No key was sent (`auth_required`), or the key was refused: unknown, revoked or expired, its holder may no longer use keys, or this instance takes none. Carries `WWW-Authenticate: Bearer`. After 60 refused keys from one IP address in a minute, every key from there is answered `429` (text, with `Retry-After`) until the minute is up.
- `403`: A read-only key tried to change something (`read_only_key`), or the account is blocked (`forbidden`).
- `429`: Too many changes in the last minute: counted per IP address, per account and per key (an admin key’s per key alone, at the limit set on Console → Rate limits). Wait the number of seconds `Retry-After` gives.
- `503`: The site is down for maintenance. The body is the maintenance page, as HTML. Try again later: `Retry-After` gives the seconds.

---

[API](https://skmtc.dev/verifiedhandles/apis/verified-handles-api.md) · [All operations](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/llms.txt) · [OpenAPI document](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/revisions/40720de2e0ec?raw)