# Apartspace

> Apartment marketplace in Ukraine and Georgia. Agents can search, price and
> propose a booking through a documented API — no browsing or form filling.

## Booking as an agent

- OpenAPI: https://apart-space.com/api/agent/v1/openapi.json
- MCP (Streamable HTTP): POST https://apart-space.com/mcp — the same surface also answers at https://apart-space.com/api/agent/v1/mcp
- The MCP endpoint speaks revisions `2026-07-28` (per-request `_meta`, `server/discover`)
  and `2025-11-25` and earlier (`initialize` handshake). Send one JSON-RPC message per POST.
- **Searching, fetching and pricing need no credential at all.** Point your client at the URL.
- Proposing a booking needs `Authorization: Bearer {credentialId}:{secret}` with `bookings:write`.
- The REST tier under https://apart-space.com/api/agent/v1 still requires a credential for everything.

### The cabinet surface

- MCP (one cabinet): POST https://apart-space.com/api/agent/v1/crm/mcp
- For a host reading their own properties, bookings and availability. Needs a token
  carrying `crm:read`; the account is taken from the token, never from an argument.
- `crm:write` additionally allows holding and freeing dates, and confirming or declining
  a booking request that is still waiting. It cannot touch a confirmed booking, cancel
  anything or change a price, and the owner is told whenever it decides a request.

### Getting a credential

- **OAuth 2.1 is the way in for an app.** Discovery: https://apart-space.com/.well-known/oauth-authorization-server
  (RFC 8414), reached from the RFC 9728 document a 401 names in its `WWW-Authenticate` header.
- Register yourself at https://apart-space.com/oauth/register (RFC 7591), or use an https
  Client ID Metadata Document URL as your `client_id`. PKCE with S256 is required; `plain` is refused.
- Send `resource` (RFC 8707) naming the exact MCP endpoint you want. A token is bound to it:
  a marketplace token is refused by the cabinet surface and the other way round.
- Access tokens last an hour; refresh tokens rotate on use. Presenting a rotated refresh token,
  or a code twice, revokes the whole grant — that is a leak signal, not a retry.
- Users see and revoke connected apps at https://apart-space.com/account/connected-apps.
- A traveller who has an Apartspace account mints one themselves at https://apart-space.com/account/agent-access
  and hands it to their agent. It carries their identity and the scopes `listings:read`,
  `bookings:write` and `crm:read`.
- Third-party products ask the operator for a service credential; those are read-only by default.
- The secret is shown once and never stored in retrievable form. Rotate by revoking and re-minting.

### What a booking actually does

- Nothing is ever booked silently. A request reaches the owner, who confirms or declines.
- With a service credential the guest must also confirm by email first; poll `request_status`
  until it leaves `pending_email_confirmation`.
- With a traveller-minted credential the traveller already authenticated, so the request goes
  straight to the owner and the response carries `booking_id` and a signed status URL.
- Prices are always re-quoted server-side. A price you send is ignored.

### MCP tools

- `search_listings` — Search listed apartments in the Apartspace marketplace.
- `get_listing` — Fetch one listed apartment by id.
- `quote_stay` — Price a stay for exact dates using the same calculator as the website.
- `create_booking_request` — Propose a booking request for a guest.
- `request_status` — Check a booking request you created: pending_email_confirmation / expired / activated (with the live owner-decision booking status).

Note the argument names differ where the history did: `quote_stay` and `get_listing` take
`id`, `create_booking_request` takes `listing_id`, `request_status` takes `request_id`.

## Human-facing surfaces

- Catalog: https://apart-space.com/gallery
- AI sitemap: https://apart-space.com/sitemap.json
- Robots: https://apart-space.com/robots.txt
- Pages answer `?_format=json` with a machine-readable document.

## Etiquette

- Rate limits apply; back off on 429.
- Do not create booking requests to probe availability — use `quote_stay`, which is free and exact.
- Guest contact details stay in the CRM; the API returns them to nobody.

_Generated by `bin/semitexa llms:generate`. Edit the command, not this file._