# PREISmonitoring API

> Programmatic access to observed prices, availability, and their history across
> the online shops, marketplaces, and platforms monitored for your account.
> Read-only. Two surfaces on one contract: REST under `/v1/*` and MCP under
> `POST /mcp`.

PREISmonitoring observes what products actually cost and whether they are
actually in stock, and it keeps the observation history. Products are addressed
by internal item ID, EAN, PZN, or ASIN together with its marketplace locale.
Nothing in this API changes monitoring configuration or platform state.

Links below are relative to this file, so they resolve correctly on both the
root deployment and a path-prefixed one.

Contract version: `1.00`
Documentation updated: `2026-09-20T11:42:05+00:00`

## Contract

- [OpenAPI specification (JSON)](openapi/openapi.json): a broadly compatible representation generated from the authoritative YAML contract. Start here if the client supports JSON more reliably than YAML.
- [OpenAPI specification (YAML)](openapi/openapi.yaml): the authoritative, machine-readable contract covering both REST and MCP.
- [Interactive API reference](docs): the same contract rendered for humans; requires JavaScript.
- [Complete API reference](llms-full.txt): the whole contract and operation guide in one text document.
- [Contract changelog](openapi/CHANGELOG.md): release dates and changes between contract versions.

## REST

- `POST /v1/auth/token`: exchange a login identifier and password for a bearer token.
- `GET /v1/sites`: the shops and platforms monitored for your account.
- `GET /v1/items`: monitored products visible in the authorized account scope, addressable by item ID, EAN, PZN, or ASIN plus locale; an empty response is not a global absence claim.
- `GET /v1/items/asin-locales`: the supported Amazon marketplace locales.
- `GET /v1/results`: price and availability observations, cursor-paged up to 10,000 records per request; time-only agent reads first enumerate visible sites and start with a site-scoped 24-hour window.
- `GET /v1/results/stream`: the same observations as NDJSON for larger extracts.
- `GET /v1/results/capabilities`: which result queries the account may run.
- `GET /v1/orders`: monitoring orders, with export and import history and downloadable artifacts.
- `GET /healthz`: runtime reachability, unauthenticated.

## MCP

- `POST /mcp`: JSON-RPC 2.0 over Streamable HTTP, secured by OAuth 2.1 authorization code flow with PKCE and the `mcp` scope.
- Discover the tool catalog and its JSON Schemas with `tools/list`; the catalog covers sites, products, monitoring orders, observation results, change deltas since a timestamp, export and import history, and market price position.
- Discover server-authored workflows with `prompts/list`: `check-price-availability`, `inspect-observation`, `analyze-market-price-position`, `review-observed-shops`. Fetching one with `prompts/get` returns a ready-to-run task description.
- Discover reference data with `resources/list` and `resources/templates/list`, including `pmon://reference/sites`, `pmon://reference/asin-locales`, and `pmon://reference/results-contract`.
- Discover the authorization server through the standard `/.well-known/` metadata endpoints before starting the flow.
- Every published tool is annotated `readOnlyHint: true`. No tool, prompt, or resource widens the authenticated account's scope.

## Access

- Request a time-limited free API account: https://www.preismonitoring.de/kontakt
- First unauthenticated request: `GET /healthz`. It returns the current contract and build versions.
- First authenticated REST request: exchange `loginIdentifier` and `password` at `POST /v1/auth/token`, then send the returned bearer token to `GET /v1/sites`.