Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: ShelfAtlas Catalog MCP API
version: 1.0.0
description: 'Read access to normalised Danish retail catalog data — products, offers, stores, and chains. Authenticate with a Bearer `sa_live_` API key. This document is the contract the official ShelfAtlas SDKs conform to. Data coverage: the offer feed covers every major Danish chain, but the curated product catalog is smaller and actively expanding — an empty data array from /products/{id}/offers or /price-history means no offers are linked to that product yet, not an error.'
termsOfService: https://shelfatlas.com/legal/terms
servers:
- url: https://api.shelfatlas.com
description: Production
security:
- bearerAuth: []
tags:
- name: MCP
paths:
/api/v1/mcp:
post:
operationId: mcpJsonRpc
summary: MCP server (JSON-RPC 2.0) — the catalog as tools for AI assistants
description: 'Model Context Protocol endpoint (stateless JSON transport). Send a JSON-RPC 2.0 request such as `{"jsonrpc":"2.0","id":1,"method":"tools/list"}` with `Accept: application/json, text/event-stream`. Same API key and monthly quota as the REST reads.'
tags:
- MCP
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: JSON-RPC 2.0 response.
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Error:
type: object
additionalProperties: true
required:
- error
properties:
error:
type: string
description: Machine-readable error code.
message:
type: string
detail:
type: string
retry_after_sec:
type: integer
description: Seconds to wait before retrying (429).
plan:
type: string
description: Caller's resolved plan id (present on monthly_limit_reached).
limit:
type: integer
description: The plan monthly request quota (present on monthly_limit_reached).
used:
type: integer
description: Requests already spent this UTC month (present on monthly_limit_reached).
resets_at:
type: string
format: date-time
description: When the quota resets — next UTC month start (present on monthly_limit_reached).
next_plan:
type: object
nullable: true
description: The cheapest plan with a larger quota, or null at the top of the ladder.
properties:
id:
type: string
name:
type: string
monthly_price_dkk:
type: integer
monthly_request_quota:
type: integer
plans_url:
type: string
format: uri
description: Public pricing page — no sign-in required.
upgrade_url:
type: string
format: uri
responses:
RateLimited:
description: Rate limit or monthly limit reached (`rate_limited` / `monthly_limit_reached`).
headers:
Retry-After:
description: Seconds to wait before retrying (present on `rate_limited`).
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing, invalid, or revoked API key (`missing_api_key` / `invalid_api_key` / `revoked_api_key`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'A ShelfAtlas API key: `Authorization: Bearer sa_live_<key>`.'
deviceTokenAuth:
type: apiKey
in: header
name: X-Device-Token
description: 'Anonymous per-device identity for POST /api/v1/observations: a UUID the client generates and keeps locally. Any UUID version is accepted — the check is purely the 8-4-4-4-12 hex-digit shape.'