# Akosi

> Akosi is HAND Protocol's booking and coordination service for small businesses. A customer, or an agent acting for one, asks for a time; the business owner confirms it. Every request starts as "requested": nothing is set until the owner confirms, and a request never stops anyone else from asking for the same time.

Times are in the business's own time zone. Customers are written to in English or Spanish.

## Ask for a time

- [Hosted pages](https://akosi.handprotocol.org/book/{business}): one page per business, with its services, the request form, and schema.org ReserveAction JSON-LD. The business's publishable key is the `data-key` of the `<akosi-booking>` element on that page.
- REST API at https://akosi.handprotocol.org/v1, with the publishable key as `Authorization: Bearer <key>`:
  - `GET /v1/services`: the services the business offers, with the questions each one asks (`intake`).
  - `GET /v1/services/{key}/slots`: the open days and the times on each, at most 31 days a call (`from` and `to` as dates like 2026-10-02).
  - `POST /v1/bookings`: ask for one of those times: `serviceKey`, `date`, `timeId`, and `customer` with a name and an email or a phone. Send an `Idempotency-Key` header so a retry cannot ask twice. The answer has status `requested`.
- [MCP server](https://akosi.handprotocol.org/mcp): Streamable HTTP, with the same publishable key as a bearer token. Tools: `list_services`, `get_slots`, `request_booking`. Request mode only.
- [Customer MCP door](https://akosi.handprotocol.org/mcp/b/{business}): Streamable HTTP, one per business, no key and no sign-in. Tools: `list_services`, `get_slots`, `request_booking`, `send_manage_link`. Request mode only. A business can switch it off.
- [Assistant page](https://akosi.handprotocol.org/book/{business}/assistant): for a customer who uses Claude, ChatGPT, or Gemini. One tap adds the customer door above to their assistant.
- [OpenAPI 3.1](https://akosi.handprotocol.org/openapi.json): the REST API, generated from the route table.

## Rules

- Say "requested, the owner confirms". Never tell a customer a time is set before the owner confirms it.
- Ask only what the service's intake asks. Never send health details.
- The customer hears back by email.
- Limits apply per key and per IP address; an answer of 429 carries `Retry-After`.

## Optional

- [The widget](https://akosi.handprotocol.org/widget.js): one script tag and a `<akosi-booking data-key="...">` element on any site.