# Albion Market — agent guide

> Public JSON API for Albion Online market data. Base URL: https://albion-market.onlinetools.directory

## Auth and limits

- No authentication. Do not send Authorization headers.
- Rate limit: 100 GET requests per minute per client.
- Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds remaining).
- On 429: JSON `{ error, code: RATE_LIMITED, retryAfter }` and Retry-After. Wait retryAfter seconds.
- CORS: * for GET/OPTIONS on agent endpoints. Link: rel=service-desc → /openapi.json.

## Workflow

1. GET /api/items?q={name} → take `items[].id` (unique names like T4_BAG, T8_SWORD@3). Never invent numeric IDs.
2. GET /api/prices?items={id}&server={west|east|europe} for raw snapshots (snake_case, matches upstream).
3. GET /api/arbitrage?item={id|name} for lowest sell vs highest buy per server/quality.
4. GET /api/routes?item={id|name} for origin→destination hops with distance and optional feeRate.

If you only have a display name, always search /api/items first. /api/arbitrage and /api/routes also accept names, but /api/prices requires unique ids.

## Endpoints

### GET /api/items
Query: q (required), limit (default 10, max 25), offset (default 0).
200: { query, count, limit, offset, items: [{ id, name, tier, enchantment, icon }], suggestion }
400 MISSING_QUERY | INVALID_LIMIT | INVALID_OFFSET
503 ITEM_INDEX_UNAVAILABLE

### GET /api/prices
Query: items (required, comma-separated unique names), server (required: europe|east|west), locations (optional cities), qualities (optional 1-5), limit (default 100, max 500), offset.
200: MarketPriceEntry[] (snake_case)
400 MISSING_ITEMS | MISSING_SERVER | INVALID_SERVER | INVALID_LOCATION | INVALID_QUALITY | INVALID_ITEM | INVALID_LIMIT | INVALID_OFFSET
429 RATE_LIMITED, 500 UPSTREAM_ERROR, 504 UPSTREAM_TIMEOUT (retryAfter: 10)

### GET /api/arbitrage
Query: item (required, id or name), servers (optional, comma-separated or all), limit (default 10, max 50), offset.
200: { item, count, opportunities: [{ server, quality, qualityLabel, buyCity, sellCity, buyPrice, sellPrice, profit, marginPercent }], errors? }
404 ITEM_NOT_FOUND includes optional suggestion — retry with that name or search /api/items.

### GET /api/routes
Query: item (required), servers, origin (one of Brecilien, Bridgewatch, Caerleon, Fort Sterling, Lymhurst, Martlock, Thetford), qualities, minProfit (default 0), maxDistance (default 50), feeRate (0-100, default 0), sort (profit|margin|distance, default profit), limit, offset.
200: { item, count, origin, feeRate, routes: [{ originCity, destinationCity, quality, buyPrice, sellPrice, rawProfit, netProfit, marginPercent, distance, server, chains }] }

### GET /api/health
200: { status, version, timestamp, uptime, docs: { openapi, llms, llmsFull, human } }

### GET /api/proxy (deprecated)
UI CORS proxy. Agents should use /api/prices.

## Enums

- servers: europe, east, west
- cities: Black Market, Brecilien, Bridgewatch, Caerleon, Fort Sterling, Lymhurst, Martlock, Thetford
- qualities: 1=Normal, 2=Good, 3=Outstanding, 4=Excellent, 5=Masterpiece

## Error recovery

All errors: { error, code, details?: [{ field, message }], retryAfter?, suggestion? }
- RATE_LIMITED / UPSTREAM_TIMEOUT: wait retryAfter, then retry
- ITEM_NOT_FOUND: use suggestion or GET /api/items?q=
- INVALID_*: fix the named field using details[].message (often lists allowed values)
- UPSTREAM_ERROR: retry once; if /api/arbitrage or /api/routes returned partial errors[], other servers still succeeded
- ITEM_INDEX_UNAVAILABLE: retry after a few seconds

## Specs

- https://albion-market.onlinetools.directory/openapi.json
- https://albion-market.onlinetools.directory/llms.txt
- https://albion-market.onlinetools.directory/api-docs