# MeshHub Tenant API

> MeshHub is execution infrastructure for AI agents: one HTTP API under
> `/api/v1/` to search, book, pay, and track real-world services
> (travel, shipping, car rental, salons, hotels). Authenticate with an
> API key in the `X-MH-Key` header — no key yet? Mint a free 7-day
> trial key: `POST /api/v1/auth/trial-keys/` (no auth, no body; capped
> per IP, so store and reuse it). State-changing operations are
> asynchronous: they return 202 with a task envelope — poll
> `GET /api/v1/tasks/{task_id}/` or subscribe to signed webhooks. All
> failures use a single flat error envelope; branch on the `error`
> slug, never on the HTTP status.
>
> MeshHub is the system of record for orders and customers: render
> order-history pages from `GET /api/v1/orders/?customer=<your-user-id>`
> and profile pages from `GET /api/v1/end-users/?external_id=<your-user-id>`
> — do not build local orders or customers tables. Keep only login
> credentials and sessions in your own database.

## Docs

- [Tenant integration guide](https://merchant.meshhub.ai/docs/tenant-integration.md): canonical end-to-end spec (auth, conventions, endpoints, webhooks, quickstart)
- [OpenAPI 3 schema, JSON](https://merchant.meshhub.ai/api/schema/?format=json): live machine-readable contract
- [OpenAPI 3 schema, YAML](https://merchant.meshhub.ai/api/schema/)
- [TypeScript SDK README](https://merchant.meshhub.ai/docs/sdk-typescript.md): `@meshhub/sdk` on npm — typed client with task polling, webhook verification, and error mapping built in
- [Thin-frontend reference example](https://merchant.meshhub.ai/docs/examples/thin-frontend.md): complete minimal shop — browser → own backend (SDK + API key) → MeshHub; the recommended app architecture

## Optional

- [AI-builder prompt](https://merchant.meshhub.ai/docs/ai-builder-prompt.md): copy-paste prompt that makes an AI app builder (e.g. Replit Agent) produce a working shop with safe key handling
- [Postman collection](https://merchant.meshhub.ai/docs/meshhub.postman_collection.json): ready-to-import request collection covering mint key → search → book → pay → orders
- [Interactive API explorer](https://merchant.meshhub.ai/api/docs/): Swagger UI over the live schema
- [API playground](https://merchant.meshhub.ai/docs/playground/): drive search → book → pay in the browser with your API key
- [Developer portal](https://merchant.meshhub.ai/docs/): human entry point linking everything above