# Save hotel stars

Content Enrichment API / Hotel Stars

`POST https://api.ygo.ai/v2/project/content/saveHotelStars`

Set your project's own star grade for one hotel. Upsert: each hotel carries at most one grade per project, and saving replaces any previous grade. This project's getEnrichedHotel, listEnrichedHotels and listEnrichedHotelSummaries then serve it as StarsMap.project and StarsMap.default, and as the top-level Stars (normally on the next read, at the latest about a minute later); no other project sees the grade. The hotel must belong to the calling project (404 otherwise), Stars must be greater than 0 and at most 10 with at most one decimal, and Superior must not be sent: a project grade has no Superior (400 otherwise).

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/saveHotelStars.json

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/saveHotelStars' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
  "Stars": 4.5
}'
```

## Authorization

`Authorization: Bearer <key>`

Project-scoped API key

## Headers

- `X-Project-ID` (string (uuid), **required**)

  Project UUID. Required for all project-scoped endpoints.

  Example: `$YGO_PROJECT_ID`

## Request body

Required.

### application/json

Schema: object, `SaveHotelStarsRequest`

Request body for setting your project's star grade for a hotel. A project grade has no Superior: a body with Superior set to `true` or `false` is refused with 400 (`null` counts as absent).

- `HotelID` (string (uuid), **required**)

  UUID of the hotel to grade. The hotel must belong to the calling project; a hotel outside the project's scope returns 404.

  Example: `0192fb17-5dc6-7abc-8def-123456789abc`
- `Stars` (number (float), **required**)

  Your project's grade for the hotel: greater than 0 and at most 10, with at most one decimal (for example 4 or 4.5). A missing value reads as 0 and is refused.

  Example: `4.5`

  Limits: > 0, max 10

#### Example request: halfStarGrade. Grade a hotel 4.5 stars

```json
{
  "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
  "Stars": 4.5
}
```

#### Example request: wholeStarGrade. Grade a hotel 4 stars

```json
{
  "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
  "Stars": 4
}
```

## Responses

### 200 OK

Grade saved. Any previous grade of this project for the hotel was replaced.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `SaveHotelStarsResponse`

Single-object response envelope wrapping the saved grade.

- `Data` (object, `HotelStars`, **required**)

  Your project's own star grade for a hotel.

  - `HotelID` (string (uuid), **required**)

    UUID of the hotel the grade applies to.

    Example: `0192fb17-5dc6-7abc-8def-123456789abc`
  - `Stars` (number (float), **required**)

    The saved grade, greater than 0 and at most 10, with at most one decimal.

    Example: `4.5`

##### Example: halfStarGrade. The saved grade

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Stars": 4.5
  }
}
```

##### Example: wholeStarGrade. The saved grade, a whole star

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Stars": 4
  }
}
```

### 400 Bad Request

Bad Request - Validation error or invalid request body.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: missingHotelID. HotelID missing

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "HotelID",
        "Message": "HotelID is required"
      }
    ]
  }
}
```

##### Example: invalidHotelID. HotelID is not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid HotelID format"
  }
}
```

##### Example: superiorSent. Superior sent: a project grade has no Superior

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "A project grade has no Superior",
    "Fields": [
      {
        "Field": "Superior",
        "Message": "A project grade has no Superior"
      }
    ]
  }
}
```

##### Example: invalidBody. Malformed request body

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid request body"
  }
}
```

##### Example: starsOutOfRange. Stars missing, below 0.1, above 10, or snapping to 0

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
    "Fields": [
      {
        "Field": "Stars",
        "Code": "OUT_OF_RANGE",
        "Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
        "Params": {
          "Min": 0.1,
          "Max": 10
        }
      }
    ]
  }
}
```

##### Example: starsTooManyDecimals. Stars with more than one decimal (no field code)

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Stars must be greater than 0 and at most 10, with at most one decimal",
    "Fields": [
      {
        "Field": "Stars",
        "Message": "Stars must be greater than 0 and at most 10, with at most one decimal"
      }
    ]
  }
}
```

### 401 Unauthorized

Unauthorized - Invalid or missing API key.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

### 403 Forbidden

Forbidden - Valid API key but insufficient permissions for this operation. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.catalog:write permission this endpoint requires.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:write"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
```

### 404 Not Found

Not Found - The hotel is not in the calling project's scope, or HotelID is the all-zeros UUID.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: hotelNotFound. Hotel not in the project

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Hotel not found"
  }
}
```

### 429 Too Many Requests

Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`
- `Retry-After` (integer)

  Number of seconds to wait before retrying the request. Present on 429 responses.

  Example: `30`

  Limits: min 1

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

### 500 Internal Server Error

Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Stars`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Stars must be greater than 0 and at most 10, with at most one decimal`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: saveFailed. The grade could not be saved

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to save project hotel stars"
  }
}
```

##### Example: accessCheckFailed. Hotel membership could not be checked

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to verify hotel access"
  }
}
```
