Automatic Speech Recognition Annotation Set REST API Reference

Use the Automatic Speech Recognition (ASR) Annotation Set REST API to define annotation sets for your skill. After you create an annotation set, you can run an ASR evaluation on the annotation set. For ASR Evaluation APIs, see Automatic Speech Recognition (ASR) Evaluation API Reference.

API endpoint

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

Authentication

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

Operations

The ASR API includes the following operations.

Operation HTTP method and URI

Create annotation set

POST /v1/skills/{skillId}/asrAnnotationSets

Delete annotation set

DELETE /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}

Get annotation set contents

GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}

Get annotation set metadata

GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}

List annotation sets

GET /v1/skills/{skillId}/asrAnnotationSets?nextToken={nextToken}&maxResults={maxResults}

Update annotations

PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations

Update metadata

PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}

Create annotation set

Create a new annotation set. Fill the annotation set with pre-recorded sample audio utterances by calling Update annotations.

Request

To create an annotation set, you make a POST request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/asrAnnotationSets
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 for which to create an annotation set.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": "QuickTrivia annotation set1"
}

Request body properties

Property Description Type Required

name

Name of the annotation set.
Valid value: up to 170 characters.

String

Yes

Response

A successful response returns HTTP 200 OK with a Location parameter in the request header. The response body contains the annotation set ID. Use the ID to reference and add sample utterances to the annotation set.

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

{
    "id": "amzn1.ask.asr-annotation-set.524575b7-d845-4b61-a472-ce6e1fe4210a"
}

Response body properties

Property Description Type Required

id

Identifies the new annotation set.

String

Yes

HTTP status codes

Status Description

200 OK

Empty annotation set created successfully. The response header contains a Location parameter that includes the skillId and annotationSetId. The annotationSetId is the same as the id in the response body. For example:

HTTP 200 OK
Content-Type: application/json
Location: /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

Delete annotation set

Delete the specified annotation set.

Request

To delete an annotation set, you make a DELETE request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

DELETE /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
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

annotationSetId

Path

Identifies the annotation set to delete.

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 204 No Content. 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

204 No Content

Annotation set deleted successfully.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

Get annotation set contents

Download the contents of the specified annotation set in comma-separated values (CSV) or JSON format.

Request

To download the contents of the annotation set, you make a GET request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: {accept-type}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

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

String

Yes

annotationSetId

Path

Identifies the annotation set.

String

Yes

maxResults

Query

Maximum number of items to return.
Include when the accept header indicates application/json format only.
Default value: 1000.

Number

No

nextToken

Query

Token that you use to get the next set of annotations, after you receive a response with truncated results. Set this parameter to the value of nextToken from the truncated response you just received.
Include when the accept header indicates application/json format only.

String

No

access token

Header

LWA token.

String

Yes

accept-type

Header

Specifies the requested format of the returned contents.
Valid values: text/csv, application/json.

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 contents of the annotation set in the specified format.

On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

CSV response body example

When you specify CSV format, the response body includes the entire contents. The first row of the response body contains comma-delimited attribute names of the annotation properties. Subsequent rows define the annotations. The annotation properties in each row follow the strict ordering of the attribute property names defined in the first row.

The following example shows a response in CSV format.

filePathInUpload,uploadId,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime

hello_world.mp3,amazn.catalog.upid.12341234,5,alexa hello world, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ

ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA,2020-04-013 13:23PM TZ

ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ

something.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ

CSV response body properties

The order of the columns doesn't matter because the first line of the CSV payload specifies the column ordering.

Property Description Type

filePathInUpload

Path to the audio file in the uploaded zip file. For example, for a zip file that contains a folder, named folder with an audio file, named audio.mp3, the path is folder/audio.mp3.
Included when expectedTranscription is missing. When filePathInUpload is present, uploadId is present also.

String

uploadId

Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload.

Included when expectedTranscription is missing. When uploadId is present, filePathInUpload is present also.

String

evaluationWeight

Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate.
Valid values: 1 – 1000, from least to most significant test case.

Integer

expectedTranscription

Expected transcription text for the input audio.
Included when uploadId and filePathInUpload are missing.
Valid values: 1 – 500 Unicode characters.

String

audioAssetDownloadUrl

Identifies the presigned URL at which to download the audio.

String

audioAssetDownloadUrlExpiryTime

Expiration date for the download URL.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

JSON response body example

The following example shows a response in JSON format.

{
    "annotations": [{

            "uploadId": "1234-12314-12314",
            "filePathInUpload": "hello_world.mp3",
            "evaluationWeight": 5,
            "expectedTranscription": "alexa hello world",
            "audioAsset": {
                "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
                "expiryTime": "2019-10-12T10:20:50.52Z"
            }
        },
        {
            "uploadId": "1234-12314-12315",
            "filePathInUpload": "ask say hello.wav",
            "evaluationWeight": 10,
            "expectedTranscription": "ask hello world skill say hello",
            "audioAsset": {
                "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
                "expiryTime": "2019-10-12T10:20:50.52Z"
            }
        }
    ]
}

JSON response body properties

Property Description Type

annotations

Sample utterances that are part of the annotation set.
Maximum size: 1000 elements.

Array of objects

annotations[].filePathInUpload

Path to the audio file in the uploaded zip file.
For example, for a zip file that contains a folder, named folder with an audio file, named audio.mp3, the path is folder/audio.mp3.

Included when expectedTranscription is missing. When filePathInUpload is present, uploadId is present also.

String

annotations[].uploadId

Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload.


Included when expectedTranscription is missing. When uploadId is present, filePathInUpload is present also.

String

annotations[].evaluationWeight

Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate.
Valid values: 1 – 1000, from least to most significant test case.

Integer

annotations[].expectedTranscription

Expected transcription text for the input audio.
Included when uploadId and filePathInUpload are missing.
Valid values: 1 – 500 Unicode characters.

String

annotations[].audioAsset

Specifies how to download the audio file.

Object

annotations[].audioAsset.audioAssetDownloadUrl

Identifies the presigned URL at which to download the audio file.

String

annotations[].audioAsset.audioAssetDownloadUrlExpiryTime

Expiration date for the download URL.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

paginationContext

Indicates there is more content. If present, the response contains a subset of the annotations. When there is no more content, paginationContext isn't included in the response.

Object

paginationContext.nextToken

Identifies the next set of annotations to return. The token expires in 24 hours.
Use this value for the nextToken parameter in a subsequent Get annotation set contents request.

String

HTTP status codes

Status Description

200 OK

Response body contains the contents of the annotation set.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

Get annotation set metadata

Get the metadata for the specified annotation set.

Request

To get the metadata for an annotation set, you make a GET request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
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

annotationSetId

Path

Identifies the annotation set.

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 annotation set metadata. 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

{
    "name": "QuickTrivia annotation set1",
    "annotationCount": 12,
    "lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
}

Response body properties

Property Description Type

name

Name of the annotation set.

String

annotationCount

Number of annotations in the annotation set.

Integer

lastUpdatedTimestamp

Timestamp of the last update to the annotation set.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

eligibleForEvaluation

(Optional) Indicates whether an evaluation can be run against the annotation set. If set to false, the annotation set is missing uploadId, filePathInUpload, expectedTranscription, or evaluationWeight.

Boolean

HTTP status codes

Status Description

200 OK

Response body contains the metadata for the annotation set.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

List annotation sets

Get all annotation sets for the specified skill.

Request

To list all annotation sets for the specified skill, you make a GET request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/asrAnnotationSets?nextToken={nextToken}&maxResults={maxResults}
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

maxResults

Query

Maximum number of items to return.
Default value: 1000.

Number

No

nextToken

Query

Token that you use to get more items in the list, after you receive a response with truncated results. Set this parameter to the value of nextToken from the truncated response you just received.

String

No

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 a list of annotation sets. 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


    "annotationSets": [{
            "id": "amzn1.ask-asr-evaluation.asid.1234-123-1234",
            "name": "my annotation set",
            "annotationCount": 10,
            "lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
        },
        {
            "id": "amzn1.ask-asr-evaluation.asid.1234-123-1235",
            "name": "my annotation set 2",
            "annotationCount": 5,
            "lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
        },
        {
            "id": "amzn1.ask-asr-evaluation.asid.1234-123-1236",
            "name": "my annotation set 3",
            "annotationCount": 5,
            "lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
        }
    ]
}

Response body properties

Property Description Type

annotationSets

List of annotation sets.

Array of objects

annotationSets[].name

Name of the annotation set.

String

annotationSets[].annotationCount

Number of annotations in the annotation set.

Integer

annotationSets[].lastUpdatedTimestamp

Timestamp of the last update to the annotation set.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

annotationSets[].eligibleForEvaluation

(Optional) Indicates whether an evaluation can be run against the annotation set. If set to false, the annotation set is missing uploadId, filePathInUpload, expectedTranscription, or evaluationWeight.

Boolean

paginationContext

Indicates there are more matching results. If present, the response contains a subset of the results. When there are no more matching results, paginationContext isn't included in the response.

Object

paginationContext.nextToken

Identifies the next set of annotations to return. The token expires in 24 hours.
Use this value for the nextToken parameter in a subsequent List annotation sets request.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of annotation sets.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

Update annotations

Add or update annotations in an existing annotation set.

Before you add or update annotations, make sure that you create a catalog and an annotation set. For more details about the API call sequence, see ASR implementation steps.

Request

To update the annotation set, you make a PUT request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations HTTP/1.1
Host: api.amazonalexa.com
Content-Type: {content-type}
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

annotationSetId

Path

Identifies the annotation set.

String

Yes

content-type

Header

Specifies the format of the included updates.
Valid values: text/csv, application/json.

String

Yes

access token

Header

LWA token.

String

Yes

CSV request body example

When you specify CSV format, the request body includes the entire contents. The first row of the request body must contain comma-delimited attribute names of the annotation properties. Subsequent rows define the annotations. The annotation properties in each row must follow the strict ordering of the attribute property names defined in the first row.

The following example shows a request in CSV format.

filePathInUpload,uploadId,weight,expectedTranscription

hello_world.mp3,amazn.upId.12341234,5,alexa hello world

ask say hello.wav,amazn.upId.12341234,10,ask hello world skill say hello

ask say hello.wav,amazn.upId.12341234,10,ask hello world skill say hello

something.wav,amazn.upId.12341234,10,ask hello world skill say hello

CSV request body properties

The order of the columns doesn't matter because the first line of the CSV payload specifies the column ordering.

Property Description Type Required

filePathInUpload

Path to the audio file in the uploaded zip file.
For example, for a zip file that contains a folder, named folder with an audio file, named audio.mp3, the path is folder/audio.mp3.

Included when expectedTranscription is missing. When filePathInUpload is present, uploadId is present also.

String

Yes

uploadId

Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload.

Included when expectedTranscription is missing. When uploadId is present, filePathInUpload is present also.

String

Yes

evaluationWeight

Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate.
Valid values: 1 – 1000, from least to most significant test case.

Integer

Yes

expectedTranscription

Expected transcription text for the input audio.
Included when uploadId and filePathInUpload are missing.
Valid values: 1 – 500 Unicode characters.

String

Yes

JSON request body example

The following example shows a request in JSON format.

{
    "annotations": [{
            "uploadId": "1234-12314-12314",
            "filePathInUpload": "hello_world.mp3",
            "evaluationWeight": 5,
            "expectedTranscription": "alexa hello world"
        },
        {
            "uploadId": "1234-12314-12315",
            "filePathInUpload": "ask say hello.wav",
            "evaluationWeight": 10,
            "expectedTranscription": "ask hello world skill say hello"
        },
        {
            "uploadId": "1234-12314-12348",
            "filePathInUpload": "ask say hello.wav",
            "evaluationWeight": 10,
            "expectedTranscription": "ask hello world skill say hello"
        },
        {
            "uploadId": "1234-12314-12348",
            "filePathInUpload": "something.wav",
            "evaluationWeight": 10,
            "expectedTranscription": "ask hello world skill say hello"
        }
    ]
}

JSON request body properties

Property Description Type Required

annotations

Sample utterances that are part of the annotation set.
Maximum size: 1000 elements.

Array of objects

Yes

annotations[].filePathInUpload

Path to the audio file in the uploaded zip file.
For example, for a zip file that contains a folder, named folder with an audio file, named audio.mp3, the path is folder/audio.mp3.

Included when expectedTranscription is missing. When filePathInUpload is present, uploadId is present also.

String

Yes

annotations[].uploadId

Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload.

Included when expectedTranscription is missing. When uploadId is present, filePathInUpload is present also.

String

Yes

annotations[].evaluationWeight

Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate.
Valid values: 1 – 1000, from least to most significant test case.

Integer

Yes

annotations[].expectedTranscription

Expected transcription text for the input audio.
Included when uploadId and filePathInUpload are missing.
Valid values: 1 – 500 Unicode characters.

String

Yes

Response

A successful response returns HTTP 204 No Content. 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

HTTP 204 No Content

Annotation set updated successfully.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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

Update metadata

Update the metadata for an annotation set.

Request

To update the annotation set, you make a PUT request to the asrAnnotationSets resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId} HTTP/1.1
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

annotationSetId

Path

Identifies the annotation set.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": "QuickTrivia annotation set10"
}

Request body properties

Property Description Type Required

name

Name of the annotation set.
Valid value: up to 170 characters.

String

Yes

Response

A successful response returns HTTP 204 No Content. 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

HTTP 204 No Content

Annotation set properties updated successfully.

400 Bad Request

Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.

The response body contains a violations array with the errors. The following example shows the response body with a validation error.

{
    "message": "Payload validations failed",
    "violations": [{
        "message": "The \"name\" property at property path \"$.name\" is outside the allowed range.",
        "code": "INVALID_STRING_LENGTH"
    }]
}

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.
The response body contains a violations array with the errors.

404 Not Found

The requested resource isn't found. For example, the skillId isn't found.

The following example shows the response body with the error and message.

{
     "message": "The skill cannot be found.",
     "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress.

429 Too Many Requests

User has exceeded the permitted rate limit.

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

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