Heyyumi AI Live Status API

openapi: 3.2.0
info:
  title: HeyYumi Live Status 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: Live Status
paths:
  /api/v1/live-status:
    post:
      operationId: create-live-status
      summary: Live status (ask the venue right now)
      description: 'Send the owner a time-sensitive question that map/review/static data can''t answer and that changes through the day — (A) is this menu item available now / today''s fresh stock / sold out (kind=item), (D) how long is the wait right now (kind=wait), (E) can a party of N get in right now (kind=seats, headcount required). Same rail as reservations: at a venue with an active owner (on the Yumi Partners app) the app gets an instant push and the response starts as status=''pending'' (5-minute answer window). The owner answers with one tap → available, limited, unavailable, soon, or not_offered; poll GET /api/v1/live-status/{queryId} (long-poll) for the outcome. To avoid re-bothering the owner, if a fresh answer already exists for the same venue+topic it''s reused instantly (reused=true), and a pending identical question is joined. If ''now'' is outside confirmed opening hours the owner is not disturbed and you get blocked=''closed_now'' immediately (do not retry — surface the hours). Venues without an active owner return 422 live_status_not_available. Do not use this for static info like hours, parking, or pet policy — answer those from search. With the `X-Map3-Sandbox: 1` header, the venue check and opening-hours guard run for real, nothing is sent to the owner, and a simulated answer arrives after about 8 seconds (queryId starts with sbx_l_, sandbox:true). The playground always runs in sandbox mode.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - placeId
              - kind
              - topic
              properties:
                placeId:
                  type: string
                  description: Canonical place id. Get it from a search first. The example is a Yumi Partner venue.
                  example: '1726507251'
                kind:
                  type: string
                  description: 'Question kind: item (menu/stock) · wait (queue) · seats (immediate seating, include headcount).'
                  example: item
                topic:
                  type: string
                  description: The subject as a bare token, not a sentence. e.g. '두바이 쫀득 쿠키', 'yellowtail', 'wait', 'party of 10'. For item, use the venue's actual menu name.
                  example: 두바이 쫀득 쿠키
                question:
                  type: string
                  description: The guest's original wording (optional), for owner context.
                  example: 지금 두바이 쫀득 쿠키 있어요?
                sandboxOutcome:
                  type: string
                  description: 'Sandbox only: the answer to simulate, available, limited, unavailable, soon, not_offered, or no_response (after 5 min). Omit for a default answer by kind. Ignored in live mode.'
      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:
                  queryId: c2e4f6a8-0000-0000-0000-000000000000
                  placeId: '11782345'
                  kind: item
                  topic: 두바이 쫀득 쿠키
                  status: pending
                  note: null
                  settled: false
                  fresh: false
                  interestedCount: 1
                  expiresAt: '2026-09-04T00:05:00.000Z'
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '404':
          description: Live status query not found (not_found)
        '422':
          description: Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Live Status
    get:
      operationId: search-live-status
      summary: Fresh live answer (optional)
      description: If a still-valid owner-confirmed answer exists for placeId + topic, it's returned without asking (found:true + status, note, verifiedAt, validUntil). Otherwise found:false — then POST to ask fresh. You usually only need POST (it reuses on its own); use this only to peek at 'just-confirmed' info without triggering anything.
      parameters:
      - name: placeId
        in: query
        required: true
        description: Canonical place id.
        schema:
          type: string
        example: '11782345'
      - name: topic
        in: query
        required: true
        description: The subject token (same as POST's topic).
        schema:
          type: string
        example: 두바이 쫀득 쿠키
      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:
                  found: true
                  queryId: c2e4f6a8-0000-0000-0000-000000000000
                  placeId: '11782345'
                  kind: item
                  topic: 두바이 쫀득 쿠키
                  status: available
                  note: null
                  verifiedAt: '2026-09-04T00:02:30.000Z'
                  verifiedBy: merchant
                  validUntil: '2026-09-04T00:32:30.000Z'
                  fresh: true
                  interestedCount: 4
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '404':
          description: Live status query not found (not_found)
        '422':
          description: Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Live Status
  /api/v1/live-status/{queryId}:
    get:
      operationId: get-live-status
      summary: Live status result (long-poll)
      description: 'Check a live question''s current status. status: pending, available, limited, unavailable, soon, not_offered, no_response (owner didn''t answer in 5 min). Pass ?wait= (max 25) to long-poll — it returns the moment the owner answers or the 5-minute window lapses (settled); if still pending, call again to fill the ~5-minute window, then report the result with the verified time. note may carry the owner''s extra memo (e.g. wait ''20분'', ''we can seat you separately''). verifiedAt = when it was confirmed; validUntil = how long the answer stays reusable for other guests (varies by kind).'
      parameters:
      - name: queryId
        in: path
        required: true
        description: The queryId returned by the create call.
        schema:
          type: string
        example: c2e4f6a8-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:
                  queryId: c2e4f6a8-0000-0000-0000-000000000000
                  placeId: '11782345'
                  kind: wait
                  topic: 웨이팅
                  status: limited
                  note: 20분
                  settled: true
                  verifiedAt: '2026-09-04T00:02:30.000Z'
                  verifiedBy: merchant
                  validUntil: '2026-09-04T00:12:30.000Z'
                  fresh: true
                  interestedCount: 3
                  createdAt: '2026-09-04T00:00:00.000Z'
                  expiresAt: '2026-09-04T00:05:00.000Z'
        '400':
          description: Invalid parameters / bulk_export_required (result window too large)
        '401':
          description: API key required or invalid
        '404':
          description: Live status query not found (not_found)
        '422':
          description: Venue can't take live questions yet (live_status_not_available) — no active owner on the Yumi Partners app
        '429':
          description: Rate limit, daily quota, or monthly quota exceeded (see Retry-After)
      tags:
      - Live Status
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.