Developers

Maana publishes one public API: a read-only feed of upcoming workshop sessions in Kyoto. AI agents and other integrations can use it to find dates, the price per person and the seats left, then give the person a link to book on maana.jp.
Access
No authentication is required. There are no API keys, accounts or sign-up, and the API is free to use. It is read-only: nothing sent to it books, holds or pays for a seat, so there is no sandbox. Responses can be read from any website.
Quickstart
List upcoming sessions for every workshop as JSON:
curl https://www.maana.jp/api/workshops/sessions
Request Markdown instead, for example to show the person a readable list:
curl -H 'Accept: text/markdown' https://www.maana.jp/api/workshops/sessions
List one workshop, with links to the Japanese pages:
curl 'https://www.maana.jp/api/workshops/sessions?workshop=tea-ceremony&lang=ja'
Parameters
GET /api/workshops/sessions takes these query parameters. All of them are optional.
  • workshop: one workshop, as one of indigo, tea-dye, earthen-wall, kyoto-botanical-teas, fermentation, tea-ceremony, tea-ceremony-night. Omit it to list every workshop.
  • from: the first date to include, as YYYY-MM-DD in Asia/Tokyo. Defaults to today, and a past date also starts today.
  • to: the last date to include, as YYYY-MM-DD in Asia/Tokyo. Defaults to 60 days after from. The range may span at most 92 days.
  • lang: en (the default) or ja, the language of the booking and workshop links.
  • format: json, md or markdown. Overrides the Accept header.
Response
The JSON response has generatedAt, the date range from and to with its timezone and currency, a booking note, a calendarUrl and the sessions in start order. unavailableWorkshops lists any workshop whose dates could not be loaded right now; every other workshop is complete.
Each session has:
  • id: a stable identifier for the session.
  • workshop: the workshop slug, its English name and the url of its page.
  • start and end: ISO 8601 times with the Asia/Tokyo offset, for example 2026-11-08T10:00:00+09:00.
  • durationMinutes: the length of the session in minutes.
  • priceJpy: the price per person in Japanese yen, or null when the price is shown only on the booking page.
  • seatsRemaining and capacity: the seats left and the total seats.
  • available: false when the session is sold out. Sold-out sessions are still listed.
  • location: the venue. When addressSentAfterBooking is true, the exact address is emailed after booking.
  • bookingUrl: opens the booking form for this session on maana.jp.
Errors
Errors return JSON with a stable error code, a message, a hint on how to fix the request and a link to these docs. An invalid parameter returns 400 and an unknown path under /api returns 404. A 502 means the booking calendar did not respond, so try again shortly. For example:
{
  "error": "invalid_from",
  "message": "Expected from=YYYY-MM-DD",
  "hint": "Send from as a calendar date in Asia/Tokyo formatted YYYY-MM-DD, for example 2026-11-01. Omit it to start today.",
  "docs": "https://www.maana.jp/developers"
}
Error codes: invalid_workshop, invalid_from, invalid_to, invalid_range, upstream_unavailable, not_found.
Booking
The API cannot book or pay for anything. To book, give the person the bookingUrl of the session they chose. It opens the booking form on maana.jp, where they enter their own details and payment and accept the workshop disclaimer. Never complete payment on their behalf.
Seats change as people book, so check the feed again before recommending a session, and do not quote prices or availability that are not in the feed.
Reference
  • OpenAPI 3.1 description: the machine-readable definition of the endpoint, its parameters and its responses.
  • llms.txt: a guide to the whole site for AI agents.
Contact

Questions about the API or workshop bookings: atelier@maana.jp