Die biotshirt API. Für KI-Agents und Entwickler.

Lies den Katalog mit ab-Preisen, zeig öffentliche Merch-Shops und stell Shop-Anfragen für Schulen, Vereine und Unternehmen. Kostenlos, mit Sandbox, OpenAPI 3.1 und MCP-Server.

API-Key erstellen OpenAPI öffnen

In 60 Sekunden startklar.

Drei Aufrufe, dann kann dein Agent Produkte lesen und eine Shop-Anfrage testen. Jede Doku-URL liefert Markdown bei Accept: text/markdown.

Zugangsdaten holen

Kostenlos, sofort, ohne Freigabe. Der Key wird einmal angezeigt.

curl -X POST https://api.biotshirt.workers.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"mein-agent","email":"du@example.org","scopes":["catalog:read","requests:write"],"mode":"sandbox"}'

Katalog lesen

Geht auch ohne Key. Preise sind brutto ab-Preise für ein bedrucktes Stück.

curl "https://api.biotshirt.workers.dev/v1/products?q=hoodie"

Shop-Anfrage in der Sandbox

Validiert alles, sendet nichts. Live mit einem bt_live_-Key an /v1/shop-requests.

curl -X POST https://api.biotshirt.workers.dev/sandbox/v1/shop-requests \
  -H "Authorization: Bearer bt_test_..." -H "Content-Type: application/json" \
  -d '{"organization":{"name":"Grundschule am Park","type":"schule","contact_name":"Anna Beispiel","email":"sekretariat@example.org"},
       "shop_name":"Grundschule am Park Merch",
       "products":[{"product":"cruiser-2-0","colors":["Navy"],"designs":[{"position":"Front mittig","width_cm":25,"logo_url":"https://example.org/logo.png"}]}]}'

Alle Endpunkte. Eine Spezifikation.

Jede Operation in der OpenAPI-Datei hat eine operationId, Beschreibung und typisierte Schemas, direkt nutzbar für Function Calling.

Methode	Pfad	Was	Scope
`GET`	`/v1/products`	Katalog: alle veredelbaren Grundprodukte mit ab-Preisen, Farben, Größen	offen (catalog:read)
`GET`	`/v1/products/{handle}`	Ein Grundprodukt inkl. Mengenstaffel	offen (catalog:read)
`GET`	`/v1/pricing`	Preismodell: Shop kostenlos, ab-Preise, Staffeln	offen (catalog:read)
`GET`	`/v1/shops`	Öffentliche Shops von Schulen, Vereinen, Unternehmen	offen (shops:read)
`POST`	`/v1/shop-requests`	Shop-Anfrage für eine Organisation stellen	requests:write
`GET`	`/v1/shop-requests/{id}`	Status einer eigenen Anfrage	requests:read
`POST`	`/v1/keys`	Kostenlose Zugangsdaten erstellen (Self-Service)	offen
`POST`	`/oauth/token`	OAuth 2.0 client_credentials, Token für 1 Stunde	offen
`POST`	`/mcp`	MCP-Server (Streamable HTTP, Tools + Resources)	optional

Sandbox: dieselben Pfade unter https://api.biotshirt.workers.dev/sandbox/.... Service-Dokument mit allen Links: https://api.biotshirt.workers.dev/

Nur die Rechte, die du brauchst.

Scopes werden bei der Key-Erstellung festgelegt. OAuth 2.0 client_credentials ist unterstützt, Metadaten unter /.well-known/oauth-protected-resource.

Scopes

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.

Sandbox und Limits

300 Requests pro Minute mit Key, 60 ohne
5 Live-Shop-Anfragen pro Key und Tag, 200 in der Sandbox
10 Keys pro Tag und IP-Adresse
Preis: 0 €. Organisationen zahlen nur bestellte Produkte.

Versionierung und Abkündigung

Version im Pfad /v1 und im Header API-Version. Innerhalb von v1 kommen nur Felder dazu, nichts fällt weg.

Abkündigungen kündigen wir mindestens 180 Tage vorher an, erkennbar an Deprecation: true und Sunset. Richtlinie: /v1/versioning, Onboarding: /v1/onboarding

Fehler sind immer JSON

Nie HTML. Jeder Fehler hat code, message, hint und bei Validierung eine fields-Liste. 429 kommt mit Retry-After.

{"error":{"code":"validation_failed",
 "message":"The shop request has invalid or missing fields.",
 "hint":"Fix the listed fields and resend.",
 "status":422,
 "fields":[{"field":"organization.email","message":"Valid email address required."}]}}

MCP-Server inklusive.

Streamable HTTP, JSON-RPC 2.0, Tools und Resources. Ein optionaler Bearer-Key schaltet Live-Anfragen frei.

Endpoint

POST https://api.biotshirt.workers.dev/mcp

Tools: search_products, get_product, get_pricing, list_public_shops, create_shop_request

Resources: llms.txt, openapi.json, products, pricing, public-shops, agents.md

CLI

Node 18+, keine Installation nötig.

npx biotshirt products --search hoodie
npx biotshirt pricing
npx biotshirt request anfrage.json   # Sandbox
npx biotshirt keys create --name mein-agent --email du@example.org

Einkaufen in bestehenden Shops

Für Käufe in öffentlichen Schul- oder Vereinsshops nutzt dein Agent das Universal Commerce Protocol des Stores: Discovery und MCP-Endpoint stehen in https://biotshirt.de/agents.md.

API-Key erstellen. Kostenlos.

Sofort gültig, keine Freigabe. Der Key wird nur einmal angezeigt. Sandbox-Keys senden nie eine echte Anfrage.