# Save hotel image pin

Content Enrichment API / Image Pins

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

Pin one of a hotel's images as the first image of the served gallery. Upsert: each hotel carries at most one pin per project, and saving replaces any previous pin. The hotel must belong to the calling project (404 otherwise), the image must belong to that hotel (404 otherwise) and be active (400 otherwise), and a room-level image can be pinned only while the hotel has no hotel-level images (400 otherwise).

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

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/saveHotelImagePin' \
  -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",
  "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa"
}'
```

## 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, `SaveHotelImagePinRequest`

Request body for pinning a hotel image. Both ids are required, valid, non-nil UUIDs.

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

  UUID of the hotel to pin an image for. The hotel must belong to the calling project; a hotel outside the project's scope returns 404.

  Example: `0192fb17-5dc6-7abc-8def-123456789abc`
- `ImageID` (string (uuid), **required**)

  UUID of the image to pin. The image must belong to the hotel (404 otherwise) and be active (400 otherwise). A room-level image can be pinned only while the hotel has no hotel-level images (400 otherwise).

  Example: `0192fb20-1aa2-7def-9abc-1122334455aa`

#### Example request: pinImage. Pin an image as the hotel's first gallery image

```json
{
  "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
  "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa"
}
```

## Responses

### 200 OK

Image pinned successfully. Any previous pin for this 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, `SaveHotelImagePinResponse`

Single-object response envelope wrapping the saved pin.

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

  The project's pinned first image for a hotel.

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

    UUID of the hotel the pin applies to.

    Example: `0192fb17-5dc6-7abc-8def-123456789abc`
  - `ImageID` (string (uuid), **required**)

    UUID of the pinned image, as saved. Note that getEnrichedHotel echoes the pin as PinnedImageID — the id of the served image at the front of Images — which can differ from this id when the gallery serves a deduplicated equivalent of the pinned image.

    Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
  - `CreatedBy` (string, **required**)

    Audit identity of who saved the pin: a user token records the user's email; a project (proj_) machine token records its project-scoped identity (e.g. 'project:\<project-uuid>').

    Example: `editor@example.com`

##### Example: pinImage. The saved pin

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
    "CreatedBy": "editor@example.com"
  }
}
```

### 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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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: invalidHotelID. HotelID missing or not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "HotelID",
        "Message": "HotelID must be a valid UUID"
      }
    ]
  }
}
```

##### Example: invalidImageID. ImageID missing or not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "ImageID",
        "Message": "ImageID must be a valid UUID"
      }
    ]
  }
}
```

##### Example: inactiveImage. The image is not active

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "ImageID",
        "Message": "Image is not active"
      }
    ]
  }
}
```

##### Example: roomLevelImage. Room-level image while the hotel has hotel-level images

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "ImageID",
        "Message": "A room-level image cannot be pinned while the hotel has hotel-level images"
      }
    ]
  }
}
```

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

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

### 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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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 the image does not belong to the hotel.

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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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"
  }
}
```

##### Example: imageNotFound. Image does not exist or belongs to another hotel

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Image not found for this hotel"
  }
}
```

### 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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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: `ImageID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `ImageID must be a valid UUID`
    - `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: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Internal error"
  }
}
```
