# Save text template

Content Enrichment API / Templates

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

Create a new text template or update an existing one. The template is matched within the project by its TemplateKey: an existing key updates that template, a new key creates one. The saved template is returned.

TemplateKey, EntityType, and Instruction are required. The default Instruction and each per-locale instruction are checked for safety before the template is stored.

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

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/saveTextTemplate' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "TemplateKey": "summary",
  "Name": "Hotel Summary",
  "EntityType": "hotel",
  "Description": "Short marketing summary shown at the top of the hotel page.",
  "Instruction": "Write a concise, factual two-sentence summary highlighting the hotel'\''s location, standout amenity, and overall character. Avoid superlatives.",
  "LocaleInstructions": {
    "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
  },
  "Status": "active",
  "RenderLayout": "prose"
}'
```

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

Request body for creating or updating a text template. The template is matched within the project by TemplateKey.

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

  Stable key identifying the template within the project (max 100 characters). The generated text for this template is stored under this key (e.g. 'summary', 'room_description'). A key may be namespaced with a leading 'group.' prefix to define a variant within a template group. Saving with an existing key updates that template; a new key creates one.

  Example: `summary`

  Limits: max length 100
- `Name` (string)

  Human-readable template name for display. Optional.

  Example: `Hotel Summary`
- `EntityType` (string, **required**)

  Whether the template produces a hotel-level text or a room-level text.

  Values: `hotel`, `room`

  Example: `hotel`
- `Description` (string)

  Free-text note describing what the template is for. Optional.

  Example: `Short marketing summary shown at the top of the hotel page.`
- `Instruction` (string, **required**)

  Default authoring instruction that guides text generation when no locale-specific override applies. Required. Limited to 12,000 characters (Unicode characters, not bytes); longer instructions are rejected.

  Example: `Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.`

  Limits: max length 12000
- `LocaleInstructions` (map of string to string)

  Per-locale authoring instructions keyed by BCP 47 language tag (e.g. 'de-DE'). When a locale has an entry here, it overrides the default Instruction for that locale; otherwise the default Instruction is used. Optional; omit or pass an empty object for no overrides. Each per-locale instruction is limited to 2,500 characters, counted independently of the base instruction, and a template carries at most 100 locale entries.

  Example:

  ```json
  {
    "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
  }
  ```

  Limits: max keys 100, each value: max length 2500
- `Status` (string)

  Lifecycle status. Only 'active' templates are used during text generation. Defaults to 'active' when omitted.

  Values: `active`, `inactive`

  Example: `active`
- `RenderLayout` (string)

  Optional rendering hint suggesting how a client should display this template's generated text. Leave empty or omit when no hint is needed.

  Values: `prose`, `highlights`, `roomcards`, `summary`

  Example: `prose`

#### Example request: createNew. Create a new hotel summary template

```json
{
  "TemplateKey": "summary",
  "Name": "Hotel Summary",
  "EntityType": "hotel",
  "Description": "Short marketing summary shown at the top of the hotel page.",
  "Instruction": "Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.",
  "LocaleInstructions": {
    "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
  },
  "Status": "active",
  "RenderLayout": "prose"
}
```

#### Example request: updateExisting. Update the room description template's instruction

```json
{
  "TemplateKey": "room_description",
  "Name": "Room Description",
  "EntityType": "room",
  "Description": "Per-room descriptive paragraph used on room cards.",
  "Instruction": "Describe the room in one short paragraph: size, bedding, view, and the most notable in-room features. Mention any balcony or terrace. Keep it neutral and concrete.",
  "LocaleInstructions": {},
  "Status": "active",
  "RenderLayout": "roomcards"
}
```

## Responses

### 200 OK

Text template created or updated successfully. Returns the saved template.

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, `SaveTextTemplateResponse`

Single-object response envelope wrapping the saved text template.

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

  A project-scoped text template. It controls one generated text per locale for either a hotel or a room, using a default authoring instruction plus optional per-locale instruction overrides.

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

    Unique template UUID.

    Example: `0192fb40-1aa2-7def-9abc-1122334455aa`
  - `ProjectID` (string (uuid), **required**)

    UUID of the project that owns this template.

    Example: `0192fb00-0000-7000-8000-000000000001`
  - `TemplateKey` (string, **required**)

    Stable key identifying the template within the project. The generated text for this template is stored under this key (e.g. 'summary', 'room_description'). A key may be namespaced with a leading 'group.' prefix to define a variant within a template group.

    Example: `summary`
  - `Name` (string)

    Human-readable template name for display. May be empty.

    Example: `Hotel Summary`
  - `EntityType` (string, **required**)

    Whether the template produces a hotel-level text or a room-level text.

    Values: `hotel`, `room`

    Example: `hotel`
  - `Description` (string)

    Free-text note describing what the template is for. May be empty.

    Example: `Short marketing summary shown at the top of the hotel page.`
  - `Instruction` (string, **required**)

    Default authoring instruction that guides text generation when no locale-specific override applies.

    Example: `Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.`
  - `LocaleInstructions` (map of string to string, **required**)

    Per-locale authoring instructions keyed by BCP 47 language tag (e.g. 'de-DE'). When a locale has an entry here, it overrides the default Instruction for that locale; otherwise the default Instruction is used. An empty object means no per-locale overrides.

    Example:

    ```json
    {
      "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
    }
    ```
  - `Status` (string, **required**)

    Lifecycle status. Only 'active' templates are used during text generation.

    Values: `active`, `inactive`

    Example: `active`
  - `RenderLayout` (string)

    Optional rendering hint suggesting how a client should display this template's generated text. Empty when no hint is set.

    Values: `prose`, `highlights`, `roomcards`, `summary`

    Example: `prose`
  - `CreatedAt` (string (date-time), **required**)

    Timestamp when the template was created (RFC3339).

    Example: `2026-03-01T08:00:00Z`
  - `UpdatedAt` (string (date-time), **required**)

    Timestamp when the template was last updated (RFC3339).

    Example: `2026-04-12T09:15:00Z`

##### Example: createNew. Newly created hotel summary template

```json
{
  "Data": {
    "ID": "0192fb40-1aa2-7def-9abc-1122334455aa",
    "ProjectID": "0192fb00-0000-7000-8000-000000000001",
    "TemplateKey": "summary",
    "Name": "Hotel Summary",
    "EntityType": "hotel",
    "Description": "Short marketing summary shown at the top of the hotel page.",
    "Instruction": "Write a concise, factual two-sentence summary highlighting the hotel's location, standout amenity, and overall character. Avoid superlatives.",
    "LocaleInstructions": {
      "de-DE": "Schreibe eine sachliche Zusammenfassung in zwei Saetzen und verwende die Sie-Form."
    },
    "Status": "active",
    "RenderLayout": "prose",
    "CreatedAt": "2026-04-12T09:15:00Z",
    "UpdatedAt": "2026-04-12T09:15:00Z"
  }
}
```

##### Example: updateExisting. Updated room description template

```json
{
  "Data": {
    "ID": "0192fb40-2bb3-7def-9abc-2233445566bb",
    "ProjectID": "0192fb00-0000-7000-8000-000000000001",
    "TemplateKey": "room_description",
    "Name": "Room Description",
    "EntityType": "room",
    "Description": "Per-room descriptive paragraph used on room cards.",
    "Instruction": "Describe the room in one short paragraph: size, bedding, view, and the most notable in-room features. Mention any balcony or terrace. Keep it neutral and concrete.",
    "LocaleInstructions": {},
    "Status": "active",
    "RenderLayout": "roomcards",
    "CreatedAt": "2026-03-01T08:00:00Z",
    "UpdatedAt": "2026-04-12T09:15:00Z"
  }
}
```

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

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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: missingRequiredFields. Required fields not provided

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "TemplateKey",
        "Message": "TemplateKey is required"
      },
      {
        "Field": "EntityType",
        "Message": "EntityType is required"
      },
      {
        "Field": "Instruction",
        "Message": "Instruction is required"
      }
    ]
  }
}
```

##### Example: invalidEntityType. EntityType is not a valid value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "EntityType must be 'hotel' or 'room'"
  }
}
```

##### Example: invalidRenderLayout. RenderLayout is not a valid value

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "RenderLayout must be one of prose, highlights, roomcards, summary"
  }
}
```

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

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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 both the content.authoring:write and content.generation:write permissions 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: `TemplateKey`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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.generation:write"
  }
}
```

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

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

### 404 Not Found

Not Found - The requested resource does not exist or is not in the calling project's scope.

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

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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: projectNotFound. Project not found

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

### 409 Conflict

Conflict - The template could not be saved because it conflicts with the current state of an existing template.

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

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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: templateConflict. Template conflict

```json
{
  "Error": {
    "Code": "ALREADY_EXISTS",
    "Message": "Text template conflicts with an existing template"
  }
}
```

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

      Human-readable validation error message for this field.

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

      Human-readable validation error message for this field.

      Example: `TemplateKey is required`
    - `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": "Failed to save text template"
  }
}
```
