Locale Cloning REST API Reference

Use the Locale Cloning REST API to clone the locale assets of your custom skill. You can use the clone to configure a new locale in the same language. For more details about skill cloning, see Clone a skill locale.

API endpoint

The endpoint of the Locale Cloning API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Locale Cloning API includes the following operations.

Operation HTTP method and URI

Clone locale

POST /v1/skills/{skillId}/stages/{stage}/cloneLocale

Get clone locale status

GET /v1/skills/{skillId}/stages/{stage}/cloneLocaleRequests/{cloneLocaleRequestId}

Clone locale

Clone the locale assets for the specified skill and source locale. You can specify one or more target locales in a single request.

Request

To create a cloned locale, you make a POST request to the cloneLocale resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/stages/{stage}/cloneLocale
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill. You can clone skills in the development stage only.
Valid values: development.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "sourceLocale": "en-US",
    "targetLocales": [
        "en-IN",
        "en-GB"
    ],
    "overwriteMode": "DO_NOT_OVERWRITE"
}

Request body properties

Property Description Type Required

sourceLocale

Set to locale to be cloned.

String

Yes

targetLocales

List of locale to create from the source locale.

Array of string

Yes

overwriteMode

Indicates whether the locale of the skill can be overwritten.
Valid value: DO_NOT_OVERWRITE, OVERWRITE. Default: DO_NOT_OVERWRITE.

String

No

Response

A successful response returns HTTP 202 Accepted, along with a Location in the header that contains a path to track the progress of the cloning request. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accepted

Request to submit a locale for cloning succeeded.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get clone locale status

Get the status of the clone locale request.

Request

To get the cloning status, you make a GET request to the cloneLocaleRequests​ resource.

Request path and header example

Copied to clipboard.

GET ​/v1​/skills​/{skillId}​/stages​/{stage}​/cloneLocaleRequests​/{cloneLocaleRequestId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill. You can clone skills in the development stage only.
Valid values: development.

String

Yes

cloneLocaleRequestId

Path

Identifies the clone locale request.
Set to ~latest to get the status of the last Clone locale request.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the status of the clone request. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "sourceLocale": "en-US",
    "status": "IN_PROGRESS",
    "targetLocales": {
        "en-IN": {
            "status": "IN_PROGRESS"
        },
        "en-GB": {
            "status": "SUCCEEDED"
        }
    }
}

Response body properties

Property Description Type

status

Overall status of the clone request. If set to MIXED, check the individual status of each target locale. If the cloning failed and overwriteMode was set to OVERWRITE, the Alexa service attempts to rollback the locale.
Valid values: FAILED, INELIGIBLE, IN_PROGRESS, MIXED, ROLLBACK_FAILED, ROLLBACK_SUCCEEDED, SUCCEEDED.

String

errors

(Optional) List of errors that occur for the clone request.

Array of objects

sourceLocale

Locale to be cloned.

String

targetLocales

List of locale to create from the source locale.

Object

targetLocales.status

Status of the clone to the specific locale. If set to MIXED, check the individual status of each target locale. If the cloning failed and overwriteMode was set to OVERWRITE, rollback is attempted.
Valid values: FAILED, INELIGIBLE, IN_PROGRESS, MIXED, ROLLBACK_FAILED, ROLLBACK_SUCCEEDED, SUCCEEDED.

String

targetLocales.errors

(Optional) List of errors that occur for the locale.

String

HTTP status codes

Status Description

200 OK

Response body contains the status of the clone request.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Locale Cloning API defines the following objects.

Locale values

Set the locale property to a locale code valid for your skill type. The following table shows valid values for the locale property.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)

Last updated: May 11, 2023