Skip to main content
Learn the conventions, authentication, and pagination patterns used across the SpaPortal API.

​
Conventions

The base URL to send all API requests is https://spaportal.cz/api/. The SpaPortal API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests. Request and response bodies are encoded as JSON.
  • HTTPS only
  • JSON bodies for POST — send Content-Type: application/json
  • Query parameters for GET filters

​
Paths and field names

API paths are versioned: 
https://spaportal.cz/api/v2
Resource paths use plural nouns: /hotels, /visit-types, /calendar/dates.

​
IDs

  • v1 — legacy numeric id; some objects also expose _id (references v2 id)
  • v2 — id is a 24-character hex string; no legacy numeric ids

​
Dates and time

Read the dates guide. Calendar dates and times use ISO 8601. Exact timestamps (e.g. createdAt, updatedAt) use millisecond precision, always in UTC, denoted by the Z suffix:
  • Date - 2026-04-01
  • Time - 2026-04-01T10:15:30.000Z

​
Currencies

Read the currencies guide. Supported currencies: CZK (Czech koruna) and EUR (Euro). Price responses include every available currency; there is no currency request parameter. Money values use the smallest currency unit. currencyExponent tells you how many decimal places to apply — for both CZK and EUR that is 2, so 1892400 equals 18,924.00. 
{ "amountMinor": 1892400, "currency": "CZK", "currencyExponent": 2 }

​
Images and thumbnails

Some entities, such as hotels, room types, and visit types, can include image URLs.
  • url points to the original image.
  • thumbnailUrl points to a smaller generated image for previews and lists.
Image collections are returned as arrays. thumbnailUrl can be null when a thumbnail is not available. 
{
  "images": [
    {
      "url": "https://spaportal-files.s3.eu-central-1.amazonaws.com/production/room-types/superior.jpg",
      "thumbnailUrl": "https://spaportal-files.s3.eu-central-1.amazonaws.com/production/thumbnails/room-types/superior.webp"
    }
  ]
}

​
Localization

Read the localization guide. Set the Accept-Language header to request localized fields. 
-H "Accept-Language: cs-CZ,de-DE,en"
API v2 accepts BCP 47 language tags in requests. Supported response locale keys are cs-CZ, de, en, and ru. Regional request tags are matched to the closest supported locale. For example, de-DE and de-AT both return localized fields under de. Localized fields are returned as objects keyed by supported response locale. 
{
  "name": {
    "cs-CZ": "Frantiskovy Lazne",
    "de": "Franzensbad"
  }
}
When Accept-Language is omitted, the API returns all supported locale keys for that field.

​
Pagination

Read the pagination guide. SpaPortal API uses cursor pagination: 
{
  "data": [],
  "pagination": { "nextCursor": "...", "hasMore": true, "total": 42 }
}
Pass cursor in GET parameters from the previous response to fetch the next page. Read the search guide. List endpoints accept search for free-text filtering — case- and diacritics-insensitive, matched across all supported languages (cs-CZ, de, en, ru) at once, so a term in any language matches. Each endpoint documents which field(s) it searches.

​
Sorting

Read the sorting guide. List endpoints accept sort as <field>:<direction> (asc or desc), for example createdAt:desc. Each endpoint documents its sortable fields and default order.

​
Includes

Read the includes guide. Use include to embed related resources (for example include=hotel) instead of making a second request. Each endpoint documents the values it supports.