Hamelyn API & Developer Documentation

Hamelyn is a Spanish re-commerce platform: we buy and sell second-hand books, music, movies and video games. This page documents the public Hamelyn API v6 at https://api.hamelyn.com and the official CLI, for developers and AI agents.

Quickstart

No account is needed for the public endpoints:

# Service health
curl https://api.hamelyn.com/api/v6/health

# Public catalog lookup by EAN / ISBN
curl https://api.hamelyn.com/api/v6/catalog/9780140449136

# Full OpenAPI 3.1 specification (all endpoints, schemas and scopes)
curl https://api.hamelyn.com/openapi.json

Authentication

All non-public endpoints require a bearer token in the Authorization header. Two token types are accepted:

Personal access tokens (hmk_…): minted with hamelyn auth login (OAuth 2.0 device flow against auth.hamelyn.com) followed by POST /api/v6/tokens. Tokens are scoped and revocable (hamelyn token revoke).
OAuth 2.0 / OpenID Connect access tokens issued by https://auth.hamelyn.com (discovery at /.well-known/openid-configuration).

Machine-readable auth metadata: RFC 9728 protected-resource metadata (includes scopes_supported). Unauthenticated requests receive 401 with a WWW-Authenticate: Bearer resource_metadata="…" hint.

The public endpoints need no key. Read-only scopes are self-served through the CLI once your account has the cli role — request it via contact if your login does not have it yet.

Scopes

Scope	Grants
`read:stocks`	Inventory stock items and product data
`read:orders`	Purchase orders from sellers
`read:ordersells`	Marketplace and store sales
`read:marketplaces`	Marketplace sync status
`read:meta`	Domain enums and operation catalog
`read:bq`	Read-only BigQuery analytics queries
`manage:tokens`	Mint, list and revoke API tokens
write scopes	Per-domain write scopes (`write:orders`, `write:stocks`, …) — restricted; each one is listed in the OpenAPI spec

Each operation in the OpenAPI spec declares the exact scopes it requires in its security section. A missing scope returns 403 listing the required and missing scopes.

Error model

Every /api/v6 response uses a stable JSON envelope; errors are never HTML:

{ "ok": false, "error": { "code": "UNAUTHORIZED", "message": "Missing Authorization header" } }

Codes: BAD_REQUEST, VALIDATION_ERROR (400) · UNAUTHORIZED, INVALID_TOKEN, TOKEN_EXPIRED, TOKEN_REVOKED (401) · FORBIDDEN (403) · NOT_FOUND (404) · CONFLICT (409) · RATE_LIMITED (429) · INTERNAL_ERROR (500). Every response carries an x-request-id header for support.

Rate limits

Authenticated endpoints: 300 requests per minute per token. Public catalog lookups: 60 requests per minute per IP, with CDN caching. Responses carry IETF rate-limit headers (RateLimit-Policy, RateLimit); exceeding the limit returns 429 with Retry-After.

Pagination & conventions

List endpoints paginate with page / per_page (max 100) and return meta: { total, page, per_page, has_more }.
The API is versioned in the path (/api/v6/…); breaking changes ship as a new version.
Operations that support the optional idempotency-key header declare it in the OpenAPI spec.

Official CLI

# macOS
curl -fsSL https://api.hamelyn.com/cli/install.sh | sh

# Windows (PowerShell)
irm https://api.hamelyn.com/cli/install.ps1 | iex

hamelyn auth login       # OAuth device flow + token minting
hamelyn stock list       # typed access to the API

Machine-readable resources

OpenAPI 3.1 spec — also at hamelyn.com/openapi.json
OAuth protected-resource metadata (RFC 9728)
API catalog (RFC 9727) — also at hamelyn.com
Agentic Resource Discovery catalog (ai-catalog.json)
llms.txt · sitemap.xml · index.md · pricing.md

When to use the Hamelyn API

Look up whether a second-hand book, record, movie or game (by EAN/ISBN) is available to buy at Hamelyn's store, with its public price.
Check Hamelyn service health before deep-linking a user to the store or the selling flow.
Authorized partners: inventory, orders, sales and marketplace sync data under scoped tokens.

Selling flow for end users: hamelyn.com · Store: tienda.hamelyn.com · Questions: contact.