Heyyumi AI Reservations API

openapi: 3.2.0
info:
  title: HeyYumi Reservations API
  version: 1.0.0
  description: 'Refined food & drink venue data (the ''oneset''): identity, location, standardized hours, menu, price band, review count, freshness, confidence, plus reservation endpoints so AI can find, recommend, and book. One curator''s notebook, served as an API.


    ## Field Mask & tiered billing

    Use the `fields` query param (comma-separated) to choose what you receive. Tokens can be tier names, `all`, or individual field names. Unknown tokens are ignored and reported via the `X-Map3-Ignored-Fields` response header. When `fields` is omitted, the default is `core`.


    ## Authentication

    Use `Authorization: Bearer ` or the `X-API-Key` header. Do not put API keys in URLs. `?api_key=` is deprecated and scheduled for removal (it will be rejected with `401 query_auth_disabled`) because URLs are commonly stored in browser, proxy, server, and error logs.


    Billing is per request: each call is billed at the highest field tier you request (returned in the `X-Map3-Units` header). `page_size` does not change tokens.

    - `core` (= 1 token/request): id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl

    - `contact_hours` (= 2 tokens/request): phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h

    - `quality` (= 2 tokens/request): reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation

    - `edge` (= 4 tokens/request): accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation

    - `media` (= 8 tokens/request): photos


    Abuse is controlled by limits, not price: per-key rate limit (requests/min) and a token cap by plan (daily on the free tier, monthly on paid plans; 429 with `Retry-After`), and a result window for the live API (100 results on the free tier, 1,000 on Starter, 5,000 on Pro and Scale). Larger or full-dataset extraction requires Bulk Export / data licensing, not paginated API calls (see Acceptable Use in the Terms).'
  contact:
    name: heyyumi
    url: https://heyyumi.ai
servers:
- url: https://api.heyyumi.ai
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Reservations
paths:
  /api/v1/reservations:
    post:
      operationId: create-reservation
      summary: Request a reservation
      description: 'Request a table reservation at any venue that takes requests (detail shows yumiBooking.canRequest=true — Yumi Partners plus most other venues). No prepayment. The request goes straight to the venue and the response starts as status=''pending'' (not yet confirmed). The owner accepting → confirmed, declining → cancelled, no response (~5 min) → expired. Poll the status endpoint (GET) for the outcome. The guest is texted progress via KakaoTalk/SMS. Non-partner venues (yumiBooking.partner=false) take requests during their own request hours (yumiBooking.requestHours, e.g. 16:30-20:00 KST — from 30 minutes before the venue opens that day, never before 10:00). Outside those hours you get 422 reservation_requests_closed (retryAfter = next start, requestHoursKst = that venue''s hours), unless you send deferIfClosed:true: then the request is held and the venue reviews it from that start time (response reviewStartsAt; the reservation time must be at least an hour after that; the guest gets the result by text or email). if the venue is closed at the requested time, 422 venue_closed_at_requested_time (pick another time); if the time is later than 2 hours before closing, 422 reservation_too_close_to_closing (latestReservation = the latest time accepted); if the venue only seats walk-ins on that weekday (detail yumiBooking.walkInOnlyDays), 422 walk_in_only_day (pick another day); when a non-partner venue is on its day off (closed today, or closed days fall before it next takes requests; detail yumiBooking.requestsResumeAt), the request isn''t held even with deferIfClosed and you get 422 venue_day_off (retryAfter = when it takes requests again; ask the guest to send it then); partner venues that are closed today also return 422 venue_day_off for any date (closedToday:true, no retryAfter — ask the guest to send it on a day the venue is open; detail yumiBooking.closedToday shows this ahead of time); venues that can''t take requests return 422 reservation_not_available (do not retry — tell the user this venue can''t be booked through HeyYumi yet). Pass idempotencyKey to safely retry the same request without creating duplicates. To test an integration, send the `X-Map3-Sandbox: 1` header: validation and the partner check run for real, but nothing is stored and no owner push or guest text goes out. You get a simulated reservation (reservationId starts with sbx_r_, sandbox:true) that settles after about 8 seconds (confirmed by default, change it with sandboxOutcome). The playground always runs in sandbox mode.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - placeId
              - reservationTime
              - guestCount
              - guestPhone
              - idempotencyKey
              properties:
                placeId:
                  type: string
                  description: Canonical place id. Get it from a search first. The example is a Yumi Partner venue.
                  example: '1726507251'
                reservationTime:
                  type: string
                  description: Requested date & time in ISO 8601 with timezone offset (future). Korea is +09:00.
                  example: '2026-12-01T19:00:00+09:00'
                guestCount:
                  type: integer
                  description: Party size (at least 1).
                  example: '2'
                guestPhone:
                  type: string
                  description: Guest phone (required) — for status texts (KakaoTalk/SMS) and no-show contact. Missing → guest_phone_required.
                  example: 010-1234-5678
                guestName:
                  type: string
                  description: Guest name (recommended) so the owner knows who's coming.
                  example: 홍길동
                guestEmail:
                  type: string
                  description: Guest email. Required when the phone is not a Korean number — we can't text international numbers, so status updates and the view/cancel link go by email. Missing → guest_email_required.
                  example: guest@example.com
                guestLanguage:
                  type: string
                  description: Language the guest reads (ISO 639-1, e.g. en, ja, zh). Guest notices go out in this language. If omitted we guess from the note and phone number.
                  example: en
                note:
                  type: string
                  description: Optional note to the owner (seating, occasion, allergies).
                idempotencyKey:
                  type: string
                  description: Stable key (e.g. a UUID) to safely retry the same reservation. Required on REST; the MCP request_reservation tool generates one if omitted, and so does the playground on each run.
                deferIfClosed:
                  type: boolean
                  description: If true, a non-partner request outside that venue's request hours (yumiBooking.requestHours, from 30 minutes before it opens that day until 20:00 KST) is held and the venue reviews it from the next start time. The response carries reviewStartsAt, and you don't need to keep polling meanwhile (the guest is told by text or email). Omit it to get 422 reservation_requests_closed.
                  example: 'true'
                sandboxOutcome:
                  type: string
                  description: 'Sandbox only: the outcome to simulate, confirmed (default), cancelled, or expired (after 5 min). Ignored in live mode.'
                  example: confirmed
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      responses:
        '200':
          description: OK
          headers:
            X-Map3-Units:
              description: Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).
              schema:
                type: integer
            X-Map3-Ignored-Fields:
              description: Comma-separated unknown field tokens that were ignored (present only when some were dropped).
              schema:
                type: string
          content:
            application/json:
              example:
                success: true
                data:
                  reservationId: b1f2c3d4-0000-0000-0000-000000000000
                  status: pending
                  placeId: '1726507251'
                  expiresAt: '2026-12-01T10:05:00.000Z'
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '404':
          description: Reservation or venue not found (venue_not_found / reservation_not_found)
        '422':
          description: 'Venue cannot take this request: reservation_not_available (this venue can''t be booked through HeyYumi yet), reservation_requests_closed (non-partner venues take requests 10:00–20:00 KST; see retryAfter, or send deferIfClosed:true to have it held and reviewed from the next 10:00, response reviewStartsAt), venue_closed_at_requested_time, or reservation_too_close_to_closing (reservation times are taken only up to 2 hours before closing; see latestReservation), walk_in_only_day (the venue only seats walk-ins on that weekday; see walkInOnlyDays), or venue_day_off (the venue is on its day off and isn''t taking or holding requests; non-partner: see retryAfter; any venue closed today: closedToday:true)'
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Reservations
  /api/v1/reservations/{id}:
    get:
      operationId: get-reservation
      summary: Reservation status (long-poll)
      description: 'Check a reservation''s current status. status: pending, confirmed, cancelled, expired, no_show. Pass ?wait= (max 25) to long-poll — it returns the moment the reservation settles (confirmed/cancelled/expired); if still pending, call again to fill the ~5-minute window, then report the final settled outcome. Sandbox ids (sbx_r_…) are polled the same way.'
      parameters:
      - name: id
        in: path
        required: true
        description: The reservationId returned by the create call.
        schema:
          type: string
        example: b1f2c3d4-0000-0000-0000-000000000000
      - name: wait
        in: query
        required: false
        description: Long-poll seconds (0-25). Omit for a one-shot check.
        schema:
          type: integer
        example: '25'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      responses:
        '200':
          description: OK
          headers:
            X-Map3-Units:
              description: Billed tokens for this call = the highest field tier requested. page_size does not affect tokens (per-request billing).
              schema:
                type: integer
            X-Map3-Ignored-Fields:
              description: Comma-separated unknown field tokens that were ignored (present only when some were dropped).
              schema:
                type: string
          content:
            application/json:
              example:
                success: true
                data:
                  reservationId: b1f2c3d4-0000-0000-0000-000000000000
                  placeId: '11782345'
                  status: confirmed
                  settled: true
                  reservationTime: '2026-09-01T19:00:00+09:00'
                  guestCount: 2
                  approvedAt: '2026-09-01T10:02:11.000Z'
                  createdAt: '2026-09-01T10:00:00.000Z'
                  expiresAt: '2026-09-01T10:05:00.000Z'
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '404':
          description: Reservation or venue not found (venue_not_found / reservation_not_found)
        '422':
          description: 'Venue cannot take this request: reservation_not_available (this venue can''t be booked through HeyYumi yet), reservation_requests_closed (non-partner venues take requests 10:00–20:00 KST; see retryAfter, or send deferIfClosed:true to have it held and reviewed from the next 10:00, response reviewStartsAt), venue_closed_at_requested_time, or reservation_too_close_to_closing (reservation times are taken only up to 2 hours before closing; see latestReservation), walk_in_only_day (the venue only seats walk-ins on that weekday; see walkInOnlyDays), or venue_day_off (the venue is on its day off and isn''t taking or holding requests; non-partner: see retryAfter; any venue closed today: closedToday:true)'
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Reservations
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Preferred: Authorization: Bearer <API_KEY>. Do not pass keys in URLs.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative header auth. Query-string api_key is deprecated.