sitecore Languages API

openapi: 3.2.0
info:
  title: Sitecore XM Cloud REST Languages API
  description: 'The Sitecore XM Cloud REST API provides endpoints for creating and managing collections, sites, pages, languages, and publishing jobs within an XM Cloud tenant. It covers the full lifecycle of site and collection management through the XM Apps system, exposes page authoring operations, and enables programmatic control of publishing workflows. The API follows RESTful conventions and is authenticated via OAuth 2.0 tokens obtained from the Sitecore Cloud Portal automation client credentials. It is organized into several functional areas: the Sites API for managing sites, site collections, and languages; the Pages API for managing site pages; and the Publishing API for creating, monitoring, and managing publishing jobs.'
  version: v1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://xmapps-api.sitecorecloud.io
  description: XM Apps Production Server
- url: https://edge-platform.sitecorecloud.io
  description: Experience Edge Platform Server
security:
- bearerAuth: []
tags:
- name: Languages
  description: Endpoints for managing language availability at the tenant and site levels, including listing supported languages and adding or removing language options.
paths:
  /api/v1/languages:
    get:
      operationId: listLanguages
      summary: List tenant languages
      description: Retrieves all languages configured at the tenant level. Languages listed here are available for assignment to individual sites within the tenant.
      tags:
      - Languages
      parameters:
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: List of tenant languages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Language'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/languages/supported:
    get:
      operationId: listSupportedLanguages
      summary: List supported languages
      description: Returns all languages supported by the XM Cloud platform that can be added to a tenant or site configuration.
      tags:
      - Languages
      parameters:
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: List of supported languages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Language'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/sites/{siteId}/languages:
    get:
      operationId: listSiteLanguages
      summary: List site languages
      description: Retrieves all languages enabled for a specific site. These languages determine the locales in which content can be authored and delivered.
      tags:
      - Languages
      parameters:
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: List of languages for the site
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Language'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addSiteLanguage
      summary: Add a language to a site
      description: Adds a language to a site, enabling content authoring and delivery in that locale. The language must be present in the list of supported languages before it can be added to a site.
      tags:
      - Languages
      parameters:
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/environmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddLanguageRequest'
      responses:
        '201':
          description: Language added to site
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/sites/{siteId}/languages/{languageId}:
    delete:
      operationId: removeSiteLanguage
      summary: Remove a language from a site
      description: Removes a language from a site, preventing further content authoring in that locale. Existing content in the language is not deleted but becomes inaccessible through the site.
      tags:
      - Languages
      parameters:
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/languageId'
      - $ref: '#/components/parameters/environmentId'
      responses:
        '204':
          description: Language removed from site
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    environmentId:
      name: sc_env
      in: query
      description: The XM Cloud environment identifier
      required: false
      schema:
        type: string
    languageId:
      name: languageId
      in: path
      description: The language identifier (e.g., en, fr-FR)
      required: true
      schema:
        type: string
    siteId:
      name: siteId
      in: path
      description: The unique identifier of the site
      required: true
      schema:
        type: string
  schemas:
    Language:
      type: object
      description: A language configuration for a tenant or site
      properties:
        isoCode:
          type: string
          description: The ISO language code (e.g., en, fr-FR, de-DE)
          example: en
        name:
          type: string
          description: The display name of the language
          example: English
        nativeName:
          type: string
          description: The language name in its native script
          example: English
    AddLanguageRequest:
      type: object
      description: Request body for adding a language to a site
      required:
      - isoCode
      properties:
        isoCode:
          type: string
          description: The ISO language code to add (e.g., fr-FR, de-DE)
    ProblemDetails:
      type: object
      description: RFC 7807 problem details response for errors
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type
        title:
          type: string
          description: A short human-readable summary of the problem
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem
        detail:
          type: string
          description: A human-readable explanation of the problem
        instance:
          type: string
          description: A URI reference identifying the specific occurrence of the problem
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via OAuth 2.0 client credentials flow. Request tokens from https://auth.sitecorecloud.io/oauth/token using automation client credentials created in the Sitecore Cloud Portal. Tokens expire after 24 hours.
externalDocs:
  description: Sitecore XM Cloud Developer Documentation
  url: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-xm-cloud.html