> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spaportal.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# List room types

> Returns room types of active hotels across the companies your public
key is scoped to. Localized fields (`category`, `description`) return
the locale keys selected by `Accept-Language`.

See the [Room type](/api/objects/room-type) object for the full field reference.


<Warning>
  **Draft:** This endpoint is still in progress. Its parameters and
  response shape may change before it is finalized.
</Warning>


## OpenAPI

````yaml /api/v2/openapi.yaml get /room-types
openapi: 3.0.3
info:
  title: SpaPortal API v2
  version: '2.0'
  description: The current SpaPortal public API.
servers:
  - url: https://spaportal.cz/api/v2
    description: Production
security:
  - spaPortalPublicKey: []
tags:
  - name: Hotels
  - name: Room types
  - name: Amenity categories
paths:
  /room-types:
    get:
      tags:
        - Room types
      summary: List room types
      description: >
        Returns room types of active hotels across the companies your public

        key is scoped to. Localized fields (`category`, `description`) return

        the locale keys selected by `Accept-Language`.


        See the [Room type](/api/objects/room-type) object for the full field
        reference.
      operationId: getRoomTypes
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/RequestId'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Number of records to return. See [Pagination](/api/pagination).
        - name: cursor
          in: query
          schema:
            type: string
            maxLength: 2000
          description: >-
            Cursor from the previous page's `pagination.nextCursor`. See
            [Pagination](/api/pagination).
        - name: hotelId
          in: query
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          description: Filter by hotel id.
        - name: beds
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10
          description: Filter by number of beds.
        - name: code
          in: query
          schema:
            type: string
            maxLength: 200
          description: Filter by exact room type code.
        - name: search
          in: query
          schema:
            type: string
            maxLength: 200
          description: >-
            Full-text search of the localized category name across all supported
            languages (case- and diacritics-insensitive). To match a code, use
            `code`.
        - name: expand
          in: query
          schema:
            type: string
            enum:
              - hotel
          description: Set to `hotel` to embed the hotel in each room type.
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - createdAt:desc
              - createdAt:asc
            default: createdAt:desc
          description: >-
            Sort order by creation time: `createdAt:desc` returns the newest
            records first, `createdAt:asc` the oldest. Records are ordered by
            their `id`, which increases with creation time, giving a stable
            total order that keeps cursor pagination exact.
      responses:
        '200':
          description: A paginated list of room types.
          headers:
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomTypesList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
        example: cs-CZ,de
      description: >-
        Comma-separated BCP 47 language tags selecting which locale keys
        localized fields return. When omitted, all locale keys are returned. See
        [Localization](/api/localization) for details.
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
      description: Optional client-provided request identifier echoed in error responses.
  headers:
    ContentLanguage:
      description: Comma-separated locale keys included in localized fields.
      schema:
        type: string
        example: cs-CZ,de
    RequestId:
      description: Request identifier for support and debugging.
      schema:
        type: string
  schemas:
    RoomTypesList:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoomType'
        pagination:
          $ref: '#/components/schemas/Pagination'
    RoomType:
      type: object
      description: >-
        **Draft:** The room-type resource is still in progress. Its response
        shape may change before it is finalized.
      required:
        - id
        - hotelId
        - code
        - category
        - beds
        - facilities
        - images
        - description
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          example: 66f16191f739705faa020003
        hotelId:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          example: 66f16191f739705faa020001
        code:
          type: string
          nullable: true
          example: SUPERIOR-DBL
        category:
          allOf:
            - $ref: '#/components/schemas/LocalizedString'
          description: Localized category name (plain text).
        beds:
          type: integer
          example: 2
        facilities:
          type: array
          items:
            type: string
          example:
            - shower
            - toilet
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        description:
          allOf:
            - $ref: '#/components/schemas/LocalizedString'
          description: Localized description (Markdown).
        hotel:
          type: object
          description: Embedded only when `expand=hotel`.
          required:
            - id
            - name
            - stars
          properties:
            id:
              type: string
              pattern: ^[0-9a-fA-F]{24}$
              example: 66f16191f739705faa020001
            name:
              allOf:
                - $ref: '#/components/schemas/HotelNameLocalizedString'
              description: >-
                Localized hotel name. Falls back to the default locale (cs-CZ),
                so it is never null.
              example:
                cs-CZ: Pawlik
                de: Pawlik-Aquaforum
            stars:
              type: integer
              nullable: true
              minimum: 1
              maximum: 5
              example: 4
      example:
        id: 66f16191f739705faa020003
        hotelId: 66f16191f739705faa020001
        code: SUPERIOR-DBL
        category:
          cs-CZ: Superior dvoulůžkový pokoj
          de: Superior Doppelzimmer
          en: Superior double room
          ru: Улучшенный двухместный номер
        beds: 2
        facilities:
          - shower
          - toilet
        images:
          - url: https://cdn.example.com/rooms/superior.jpg
            thumbnailUrl: https://cdn.example.com/rooms/superior-thumbnail.jpg
        description:
          cs-CZ: Prostorný pokoj s vlastní koupelnou.
          de: Geräumiges Zimmer mit eigenem Bad.
          en: Spacious room with a private bathroom.
          ru: Просторный номер с собственной ванной комнатой.
    Pagination:
      type: object
      required:
        - limit
        - nextCursor
        - hasMore
        - total
      properties:
        limit:
          type: integer
          example: 25
        nextCursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page. Null on the last page.
        hasMore:
          type: boolean
        total:
          type: integer
          description: Total number of matching records across all pages.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - missing_authentication
                - invalid_authentication
                - insufficient_scope
                - not_found
                - conflict
                - rate_limited
                - internal_error
            message:
              type: string
            details:
              type: array
              items:
                type: object
                additionalProperties: true
            requestId:
              type: string
    LocalizedString:
      type: object
      additionalProperties: false
      properties:
        cs-CZ:
          type: string
          nullable: true
        de:
          type: string
          nullable: true
        en:
          type: string
          nullable: true
        ru:
          type: string
          nullable: true
      description: >-
        Localized field keyed by supported response locale (`cs-CZ`, `de`, `en`,
        `ru`). When `Accept-Language` is set, only the matched keys are
        returned.
      example:
        cs-CZ: Český text
        de: Deutscher Text
    Image:
      type: object
      required:
        - url
        - thumbnailUrl
      properties:
        url:
          type: string
          description: Original image URL.
        thumbnailUrl:
          type: string
          nullable: true
          description: Generated preview image URL, or null when unavailable.
    HotelNameLocalizedString:
      type: object
      additionalProperties: false
      properties:
        cs-CZ:
          type: string
          minLength: 1
        de:
          type: string
          minLength: 1
        en:
          type: string
          minLength: 1
        ru:
          type: string
          minLength: 1
      description: >-
        Localized hotel name keyed by supported response locale (`cs-CZ`, `de`,
        `en`, `ru`). Missing requested translations fall back to the Czech name,
        so every returned value is a non-empty string.
      example:
        cs-CZ: Spa Resort Pawlik
        de: Kurhotel Pawlik
  responses:
    BadRequest:
      description: Invalid request.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid API key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    spaPortalPublicKey:
      type: apiKey
      in: header
      name: X-SpaPortal-Public-Key
      description: >-
        See [Authentication](/api/authentication) for how to obtain and send
        your public key.

````