# Alamy API documentation

> Programmatic access to the Alamy archive. Requests go to https://api.alamy.com/v3. The complete machine-readable contract is the OpenAPI 3.0.0 document at https://api-reference.alamy.com/openapi.json.

Read the OpenAPI document rather than these HTML pages when generating a client or reasoning about request and response shapes - it is the same artefact the reference UI renders, and that page is populated by JavaScript.

## OpenAPI specification

- [OpenAPI 3.0.0 (JSON)](https://api-reference.alamy.com/openapi.json): 8 operations, schemas and security schemes. Derived from the YAML at build time, so the two cannot differ.
- [OpenAPI 3.0.0 (YAML)](https://api-reference.alamy.com/openapi.yaml): byte-identical to the source at https://api-reference.alamy.com/openapi/openapi-spec.yml.

## Operations

- [POST /token](https://api-reference.alamy.com/api-reference/#/operations/token): Acquire access token based on client credentials (tag: Authentication; operationId: `token`)
- [GET /download/{id}](https://api-reference.alamy.com/api-reference/#/operations/downloadItemById): Download a media item (tag: Download; operationId: `downloadItemById`)
- [POST /download/{id}](https://api-reference.alamy.com/api-reference/#/operations/downloadItemByIdLicensed): Download a media item declaring the license it will be used with & optionally a pre-purchased pack for payment (tag: Download; operationId: `downloadItemByIdLicensed`)
- [GET /feed](https://api-reference.alamy.com/api-reference/#/operations/feed): Retrieve media item change notifications (tag: Feed; operationId: `feed`)
- [GET /item/{id}](https://api-reference.alamy.com/api-reference/#/operations/item): Retrieve metadata for a single media item (tag: Item; operationId: `item`)
- [GET /item](https://api-reference.alamy.com/api-reference/#/operations/items): Retrieve metadata for multiple media items (tag: Item; operationId: `items`)
- [GET /orders](https://api-reference.alamy.com/api-reference/#/operations/orders): Retrieve user order history (tag: Orders; operationId: `orders`)
- [GET /search](https://api-reference.alamy.com/api-reference/#/operations/search): Search for media items (tag: Search; operationId: `search`)

## Documentation

- [Alamy API overview](https://api-reference.alamy.com/): What the API offers, the base URL, and how to request access.
- [Getting started](https://api-reference.alamy.com/getting-started/): The base URL, and where to find the API key and secret you exchange for an access token.
- [Guidance](https://api-reference.alamy.com/guidance/): Endpoint behaviour, pagination and result-set limits, request limits, and how to read the NinJS rights and metadata flags.
- [Errors](https://api-reference.alamy.com/errors/): Every status code the API returns, the two error body shapes, which are retryable, and why a download must not be blind-retried.
- [Building an integration with AI coding tools](https://api-reference.alamy.com/ai-tools/): The machine-readable entry points, generating a client from the contract, which endpoints have side effects, a read-only scope setup, and the pre-production account for testing downloads.
- [API reference (interactive)](https://api-reference.alamy.com/api-reference/): Browsable reference UI. It renders client-side, so read the OpenAPI document above instead when working programmatically.
- [FAQ](https://api-reference.alamy.com/faq/general/): Access, supported ids, release flags, and whether calling download costs money.
- [Transitioning from API V2 to V3](https://api-reference.alamy.com/faq/migrating-v2-v3/): Parameter-by-parameter mapping from the legacy V2 XML Search API to V3.
- [Changelog](https://api-reference.alamy.com/changelog/): Changes to the public API contract, newest first.

## Optional

- [Full documentation text](https://api-reference.alamy.com/llms-full.txt): the markdown source of the guides in one file.
- [Sitemap](https://api-reference.alamy.com/sitemap.xml): every HTML page on this site.