# MinpakuX

> Micro-PMS SaaS for minpaku/minsu operators in East Asia. Property management, booking, availability, and local guides.

## API

- Base URL: https://minpakux.solanalink.jp/api/v1
- Auth: `Authorization: Bearer <token>` (API key `mop_live_*` or OAuth access token `mpx_at_*`)
- Rate limit: 60 requests/minute per token
- Format: JSON responses with `data`, `meta` envelope

## Endpoints

### Properties

- `GET /api/v1/properties` — Search properties. Params: region (JAPAN|KOREA|TAIWAN), city, status, limit, offset
- `GET /api/v1/properties/{id}` — Property details with rooms, host info, refund policy
- `GET /api/v1/properties/{id}/rooms` — List rooms with full pricing details
- `GET /api/v1/properties/{id}/reviews` — Guest reviews with category ratings. Params: limit, offset

### Availability & Pricing

- `GET /api/v1/availability` — Room availability calendar. Params: propertyId (required), roomId, startDate, endDate (YYYY-MM-DD, max 90 days)
- `POST /api/v1/pricing` — Calculate pricing for a room and date range. Body: { roomId, checkInDate, checkOutDate, guests? }

### Bookings

- `POST /api/v1/bookings` — Create reservation (supports Idempotency-Key header). Body: { propertyId, roomId, checkInDate, checkOutDate, adults, children, infants, guest: { name, email, phone? }, specialRequests? }
- `POST /api/v1/bookings/dry-run` — Simulate booking (price check, no reservation created). Body: { propertyId, roomId, checkInDate, checkOutDate, adults, children }
- `GET /api/v1/bookings/{id}` — Get booking details
- `POST /api/v1/bookings/{id}/cancel` — Cancel booking with refund. Add `X-Confirm: true` header to execute; omit for preview

### Local Guides

- `GET /api/v1/guides` — Local area guides. Params: propertyId (required), type, limit, offset

### OAuth 2.1 (Agent Delegation)

- `GET /api/v1/oauth/authorize` — Start authorization flow (PKCE required, S256 only)
- `POST /api/v1/oauth/token` — Exchange auth code or refresh token for access token
- `POST /api/v1/oauth/introspect` — Check token validity (RFC 7662)
- `POST /api/v1/oauth/revoke` — Revoke access or refresh token (RFC 7009)

## Scopes

- `properties:read` — Read property listings, rooms, and reviews
- `availability:read` — Check availability, run dry-runs, calculate pricing
- `guides:read` — Access local guides
- `bookings:read` — Read booking details
- `bookings:write` — Create reservations and cancel bookings

## Markets

- Japan (minpaku / 民泊)
- Korea (minbak / 민박)
- Taiwan (minsu / 民宿)

## Languages

Content available in: English (en), Chinese Simplified (zh), Chinese Traditional (zh-TW), Japanese (ja), Korean (ko)

## Developer Portal

Register for API keys at: https://minpakux.solanalink.jp/en/developer

## OAuth 2.1 Flow (for delegated agent access)

1. Register OAuth client via Developer Portal → get client_id + client_secret
2. Redirect host to: `GET /api/v1/oauth/authorize?response_type=code&client_id={id}&redirect_uri={uri}&scope={scopes}&code_challenge={S256}&code_challenge_method=S256`
3. Host approves on consent screen → redirected back with `?code={auth_code}`
4. Exchange code: `POST /api/v1/oauth/token` with grant_type=authorization_code, code, code_verifier
5. Use access token: `Authorization: Bearer mpx_at_...` (expires in 1 hour)
6. Refresh: `POST /api/v1/oauth/token` with grant_type=refresh_token (30-day refresh tokens)

## Booking Workflow

1. Search properties: `GET /api/v1/properties?city=Tokyo&region=JAPAN`
2. Browse rooms: `GET /api/v1/properties/{id}/rooms`
3. Check availability: `GET /api/v1/availability?propertyId={id}&startDate=2026-04-01&endDate=2026-04-05`
4. Price check: `POST /api/v1/pricing` with roomId, dates, and guest count
5. Create booking: `POST /api/v1/bookings` with full guest details
6. Get booking: `GET /api/v1/bookings/{id}`
7. Cancel (if needed): `POST /api/v1/bookings/{id}/cancel` (preview first, then with `X-Confirm: true`)

## Skills (Agent Capability Files)

- [Search Properties](/skills/minpakux-search.md) — find accommodation by location and filters
- [Book Accommodation](/skills/minpakux-book.md) — end-to-end booking workflow
- [Check Availability](/skills/minpakux-availability.md) — availability calendar and pricing
- [Local Guides](/skills/minpakux-guides.md) — restaurants, transport, attractions
- [Manage Bookings](/skills/minpakux-manage.md) — host booking management via OAuth

## MCP Server

Install: `npx @minpakux/mcp-server` (set `MINPAKUX_API_KEY` env var)

## Links

- Production: https://minpakux.solanalink.jp
- API Docs: https://minpakux.solanalink.jp/en/api-docs
- OpenAPI Spec: https://minpakux.solanalink.jp/openapi.json
- Agent Card: https://minpakux.solanalink.jp/.well-known/agent.json
- Skills: https://minpakux.solanalink.jp/skills/