# biotshirt Agent API

> Machine interface for biotshirt (https://biotshirt.de): free, branded merch shops for schools, clubs, companies, craft businesses and restaurants in Germany and Austria. Sustainable textiles with the organization's logo, no minimum order quantity, every member orders and pays individually, shop live within 48 hours. This host serves the REST API, the OpenAPI document, the MCP server and the developer portal.

## When to use this API

- A user wants a free, own merch shop with their logo for a school, club, company, craft business or restaurant in Germany or Austria: read the catalog, show from-prices, then create a shop request (sandbox first, live with a bt_live_ key).
- A user asks what merch would cost: use /v1/pricing (shop setup is free, from-prices per printed piece, minimum quantity 1).
- A user wants to buy from an existing school or club shop: list shops here, then shop through the store's UCP/MCP endpoint listed in https://biotshirt.de/agents.md.
- Not for: screen printing (not offered), embroidery (paused), delivery outside DE/AT, blank garments without logo, creator print-on-demand.

## How to call it

1. Read [OpenAPI 3.1](https://api.biotshirt.workers.dev/openapi.json). Every operation has an operationId, description and typed schemas.
2. Create free credentials: `POST https://api.biotshirt.workers.dev/v1/keys` with {"name","email","scopes","mode":"sandbox"|"live"}. Keys are shown once. OAuth 2.0 client credentials: `POST https://api.biotshirt.workers.dev/oauth/token`. Metadata: https://api.biotshirt.workers.dev/.well-known/oauth-protected-resource and https://api.biotshirt.workers.dev/.well-known/oauth-authorization-server.
3. Scopes (least privilege): `catalog:read` (Read base products, printed from-prices, colors, sizes and availability.) · `shops:read` (List the public merch shops hosted on biotshirt.de.) · `requests:write` (Create a shop request (Anfrage) on behalf of an organization.) · `requests:read` (Read the status of shop requests created with the same credentials.)
4. Sandbox: same endpoints under `https://api.biotshirt.workers.dev/sandbox/...` or any bt_test_ key. Nothing is sent, everything is validated.
5. Errors are always JSON: {"error":{"code","message","hint","status","docs"}}. 429 carries Retry-After.
6. MCP: `POST https://api.biotshirt.workers.dev/mcp` (JSON-RPC 2.0). Tools: search_products, get_product, get_pricing, list_public_shops, create_shop_request. Resources: llms.txt, openapi.json, products, pricing, public-shops, agents.md.
7. Versioning: path /v1 + header API-Version; v1 is additive-only; deprecations announced 180 days ahead via Deprecation/Sunset headers, policy at https://api.biotshirt.workers.dev/v1/versioning. Onboarding (free tier, self-serve keys, sandbox) machine-readable at https://api.biotshirt.workers.dev/v1/onboarding.
8. Limits (free tier): 300 requests/min with key, 60/min anonymous, 5 live shop requests per key and day.

## Links

- [Developer portal](https://api.biotshirt.workers.dev/developers): quickstart, keys, sandbox, CLI (also as Markdown via Accept: text/markdown)
- [Service document](https://api.biotshirt.workers.dev/): every resource as JSON links
- [Store agents.md](https://biotshirt.de/agents.md): UCP discovery, policies, contact
- [Store llms.txt](https://biotshirt.de/llms.txt)
- [Website](https://biotshirt.de/) · [Request a shop (web form)](https://biotshirt.de/pages/shop-anfrage) · [Contact](https://biotshirt.de/pages/kontakt-formular)

## Guidelines

- Submit a live shop request only when the user explicitly wants a shop built; use the organization's real contact email.
- Identify agent traffic with a descriptive User-Agent. Back off on 429.
- Supplier and production details are not part of this API; prices are final consumer prices (gross, incl. 19 % VAT) unless marked netto.