openapi: 3.1.0
info:
  title: Provyl — Client API
  version: "1.0"
  summary: Room devices (IoT), the stay, TV channels and smart apps of a hotel.
  description: |
    Plain HTTPS and JSON. Send **one** credential header:

    - `X-Api-Key: pcr_…` — a partner's app or server; every room of one site, rooms addressed by room number.
      Keys are made by a site administrator in **Settings → Integrations → Client API**.
    - `X-Guest-Token: …` — a guest's phone; only the paired room, until check-out.

    Every answer is `{ "status": "success", "data": … }` or `{ "status": "error", "error": { "statusCode", "message" } }`.
    A command answers `200` only when the device changed; `502`/`504` mean it did not (retry once — values are absolute).
    The guide with a Try-it panel for every request: https://docs.provyl.com/client-api
  contact:
    name: Provyl
    url: https://docs.provyl.com/client-api
servers:
  - url: https://api.provyl.com/v1
security:
  - apiKey: []
  - guestToken: []
tags:
  - name: Room devices
    description: Lights, temperature, curtains, courtesy panel, sensors, scent — read, control, follow live.
  - name: Reference
    description: Thing types and tags.
  - name: Stay
  - name: TV
    description: Channels and smart apps, as the room shows them.
paths:
  /rooms/{roomId}/things:
    get:
      tags: [Room devices]
      operationId: listThings
      summary: List the things in a room
      description: Every enabled thing of the room with its last-known values. `?live=true` reads the building first (slower, freshest).
      parameters:
        - $ref: '#/components/parameters/roomId'
        - $ref: '#/components/parameters/live'
      responses:
        '200':
          description: The room and its things
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data: { $ref: '#/components/schemas/RoomThings' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /rooms/{roomId}/things/{thingId}:
    get:
      tags: [Room devices]
      operationId: getThing
      summary: Read one thing
      parameters:
        - $ref: '#/components/parameters/roomId'
        - $ref: '#/components/parameters/thingId'
        - $ref: '#/components/parameters/live'
      responses:
        '200':
          description: The thing as it stands
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data: { $ref: '#/components/schemas/Thing' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      tags: [Room devices]
      operationId: controlThing
      summary: Control a thing
      description: |
        Sets one component of one thing. Answers `200` only once the building accepted it, with the device as it now stands.
        Commands to one component run one at a time; a newer value replaces one still waiting. Guests are limited to the
        hotel's ranges (e.g. 20–25 °C); 60 commands a minute per room for guests, 240 for a partner key.
      parameters:
        - $ref: '#/components/parameters/roomId'
        - $ref: '#/components/parameters/thingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [componentId, value]
              properties:
                componentId: { type: string, examples: [OnOff, Dimming, TargetTemperature, Level, Position] }
                value: { type: string, description: Always a string; the component's definition gives the type., examples: ['1', '50', '22.5'] }
      responses:
        '200':
          description: The device changed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: object
                    properties:
                      roomId: { type: string }
                      thingId: { type: string }
                      componentId: { type: string }
                      value: { type: string }
                      durationMs: { type: integer, description: End to end; ~250 ms is ordinary, over a second means the building is slow. }
                      components: { type: array, items: { $ref: '#/components/schemas/Component' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooMany' }
        '502': { $ref: '#/components/responses/NotApplied' }
        '504': { $ref: '#/components/responses/NotApplied' }
  /things/{thingId}:
    patch:
      tags: [Room devices]
      operationId: renameThing
      summary: Rename a thing (API key only)
      description: The id moves with the name — use the `id` in the answer from then on. `everywhere` renames every thing of the site with the same current name.
      security:
        - apiKey: []
      parameters:
        - $ref: '#/components/parameters/thingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                alias: { type: string, maxLength: 80 }
                description: { type: string, maxLength: 500 }
                everywhere: { type: boolean, default: false }
      responses:
        '200':
          description: Renamed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: object
                    properties:
                      id: { type: string }
                      alias: { type: string }
                      description: { type: [string, 'null'] }
                      things: { type: array, items: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /rooms/{roomId}/events:
    get:
      tags: [Room devices]
      operationId: roomEvents
      summary: Follow a room live (Server-Sent Events)
      description: |
        Sends only what changed, read from the building every few seconds. Keepalive comments; the server closes after about
        two minutes — reconnect and read the room once. Browsers using `EventSource` may pass `?key=` instead of the header.
      parameters:
        - $ref: '#/components/parameters/roomId'
      responses:
        '200':
          description: 'An event stream. Each event data line is JSON: type values, roomId, and data — the things that changed, each with id, type and components.'
          content:
            text/event-stream:
              schema: { type: string }
  /types:
    get:
      tags: [Reference]
      operationId: listTypes
      summary: Thing types, their components, ranges and default presets
      responses:
        '200':
          description: Types
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type: { type: string }
                        wireType: { type: string }
                        vendor: { type: string }
                        tags: { type: array, items: { type: string } }
                        defaultPresets: { type: object, additionalProperties: { type: object, additionalProperties: { type: string } } }
                        components:
                          type: array
                          items:
                            type: object
                            properties:
                              componentId: { type: string }
                              valueType: { type: string }
                              settable: { type: boolean }
                              range: { type: object, properties: { min: { type: string }, max: { type: string } } }
                              limits: { type: object, properties: { min: { type: string }, max: { type: string } } }
                              enum: { type: array, items: { type: object, properties: { value: { type: string }, label: { type: string } } } }
  /tags:
    get:
      tags: [Reference]
      operationId: listTags
      summary: The site's tags and their wording
      responses:
        '200':
          description: Tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, examples: [BED_LIGHT] }
                        alias: { type: string, description: The hotel's wording — show this, branch on id. }
                        description: { type: [string, 'null'] }
  /rooms/{roomId}/stay:
    get:
      tags: [Stay]
      operationId: getStay
      summary: Who is staying in the room
      description: '`guest` is null when the room is vacant. A guest from a PMS is shown by name only while in house.'
      parameters:
        - $ref: '#/components/parameters/roomId'
      responses:
        '200':
          description: The stay
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: object
                    properties:
                      hotel: { type: object, properties: { id: { type: string }, name: { type: string } } }
                      room: { type: object, properties: { number: { type: string }, status: { enum: [occupied, vacant] } } }
                      guest:
                        type: [object, 'null']
                        properties:
                          name: { type: string }
                          language: { type: string, examples: [en, ko, de] }
                          checkinAt: { type: string, format: date-time }
        '404': { $ref: '#/components/responses/NotFound' }
  /channels:
    get:
      tags: [TV]
      operationId: listChannels
      summary: TV channels, in the room's order
      description: With a guest token, the guest's room. With an API key, the site — or `?room=` for what that room shows (its room type's order).
      parameters:
        - $ref: '#/components/parameters/room'
      responses:
        '200':
          description: Channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data: { type: array, items: { $ref: '#/components/schemas/Channel' } }
        '404': { $ref: '#/components/responses/NotFound' }
  /apps:
    get:
      tags: [TV]
      operationId: listApps
      summary: Smart apps, in the room's order
      parameters:
        - $ref: '#/components/parameters/room'
      responses:
        '200':
          description: Apps
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { const: success }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: The webOS app id the TV launches., examples: [netflix, youtube.leanback.v4] }
                        title: { type: string }
                        description: { type: [string, 'null'] }
                        icon: { type: [string, 'null'], format: uri }
components:
  securitySchemes:
    apiKey: { type: apiKey, in: header, name: X-Api-Key }
    guestToken: { type: apiKey, in: header, name: X-Guest-Token }
  parameters:
    roomId: { name: roomId, in: path, required: true, schema: { type: string }, description: The room number as in the console, e.g. 632., example: '632' }
    thingId: { name: thingId, in: path, required: true, schema: { type: string }, example: 632_desk-lamp }
    live: { name: live, in: query, required: false, schema: { type: boolean }, description: Read the building before answering. }
    room: { name: room, in: query, required: false, schema: { type: string }, description: 'API key only: the list as this room shows it.' }
  schemas:
    Component:
      type: object
      properties:
        componentId: { type: string }
        value: { type: [string, 'null'] }
        valueType: { type: string, examples: [Boolean, Int8, Float, Enum] }
        settable: { type: boolean }
    Thing:
      type: object
      properties:
        id: { type: string }
        type: { type: string, examples: [DIMMABLE_LIGHT, ONOFF_LIGHT, THERMOSTAT, CURTAIN, COURTESY_PANEL, OCCUPANCY_SENSOR, SCENT_DIFFUSER] }
        wireType: { type: string }
        alias: { type: string }
        description: { type: [string, 'null'] }
        tags: { type: array, items: { type: string } }
        hidden: { type: boolean }
        presets: { type: object, additionalProperties: { type: object, additionalProperties: { type: string } } }
        components: { type: array, items: { $ref: '#/components/schemas/Component' } }
    RoomThings:
      type: object
      properties:
        roomId: { type: string }
        roomType: { type: [string, 'null'] }
        displayName: { type: [string, 'null'] }
        vendorSeenAt: { type: [string, 'null'], format: date-time }
        mode: { enum: [live, mock], description: mock = a simulated site; nothing reaches the building. }
        things: { type: array, items: { $ref: '#/components/schemas/Thing' } }
    Channel:
      type: object
      properties:
        id: { type: string }
        number: { type: integer }
        name: { type: string }
        kind: { enum: [tv, radio] }
        icon: { type: [string, 'null'], format: uri }
        encrypted: { type: boolean }
        tune: { type: object, description: The input of the LG IDCAP request tv/channel/change/request — for the TV, not the phone. }
    Error:
      type: object
      properties:
        status: { const: error }
        error:
          type: object
          properties:
            statusCode: { type: integer }
            message: { type: string }
            reason: { enum: [timeout, refused] }
            durationMs: { type: integer }
            checked: { enum: [not-applied, unverified] }
  responses:
    BadRequest: { description: A field is missing or the device does not accept the value., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Unauthorized: { description: No credential, or an invalid, revoked or expired one (a guest token ends at check-out)., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Forbidden: { description: Read-only component, or not allowed with this credential., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    NotFound: { description: No such room, thing or component (another room, for a guest)., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    TooMany: { description: Too many commands — wait Retry-After seconds., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    NotApplied: { description: The building refused (502) or did not answer in time (504); the device did not change. Retry once., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
