Job Management API
You can use the APIs described in this document to create and manage jobs that automatically update reference-based catalogs. For details about catalogs, see Interaction Model Catalog Management REST API Reference.
This document describes two types of jobs that you can define: CatalogAutoRefresh, which you can use to update catalogs, and ReferencedResourceVersionUpdate, which you can use to update slot types and interaction models.
An execution is a different type of resource that models the time and status of the job. For example, an execution of a CatalogAutoRefresh job has a time stamp that specifies when the execution of the job starts, and a status to describe the state of the execution. Executions are scheduled automatically when you create a job and also when a previous execution is finished. You can read the details of all executions of a job. You can also cancel the next execution of a job.
The endpoint for SMAPI operations is https://api.amazonalexa.com. Each request must have an Authorization
header with its value set to the access token retrieved from Login with Amazon.
See also: Alexa Skills Kit Command Line Interface and Alexa Skill Management API Overview
- Create a Job Definition
- Read Job Definition
- List Jobs for Vendor ID
- Delete Job
- List Execution History
- Cancel Next Execution
- Enable or Disable Job
Create a Job Definition
You can create two types of job definitions: CatalogAutoRefresh and ReferencedResourceVersionUpdate. For example, you can use this API with the type set to CatalogAutoRefresh to specify a catalog ID and how often you want the catalog to get updated. In your skill you can specify the referenced entity that you want to get triggered for an update whenever the catalog is refreshed. Skills can use this API with the type set to ReferencedResourceVersionUpdate to link a catalog ID with a skill ID.
For skills with shared slots, invoke this API twice with the type set to ReferencedResourceVersionUpdate in both invocations. In the first invocation, link a catalog ID with a slot ID. Then, link the slot ID with a skill ID.
Request
POST /v1/skills/api/custom/interactionModel/jobs
Body for CatalogAutoRefresh
{
"vendorId": "String",
"jobDefinition": {
"type": "CatalogAutoRefresh",
"resource": {
"id": "String",
"type": "Catalog"
},
"trigger": {
"type": "Scheduled",
"hour": Integer,
"dayOfWeek": Integer
},
"status": "Enum"
}
}
Request Body Parameters for CatalogAutoRefresh
Field | Description | Parameter Type | Required? |
---|---|---|---|
vendorId |
To get your vendor ID, go to https://developer.amazon.com/mycid.html. | String | Yes |
jobDefinition.type |
"CatalogAutoRefresh" | String | Yes |
resource.id |
The ID of the resource. | String | Yes |
resource.type |
"Catalog", "SlotType", or "InteractionModel" | String | Yes |
trigger.type |
"Scheduled" | String | Yes |
trigger.hour |
Starting hour of the day for the execution to run. Set it to 0, 4, 8, 12, 16, or 20. | Integer | Yes |
trigger.dayOfWeek |
The day of week. Specify this value to indicate that you want the job to be scheduled weekly. If you don't specify a value here, the job runs daily by default. | Integer | Required for weekly schedule. |
status |
Set to "ENABLED" or let it be null. | Enum | No |
Body for ReferencedResourceVersionUpdate
{
"vendorId": "String",
"jobDefinition": {
"type": "ReferenceVersionUpdate",
"resource": {
"type": Enum,
"id": "String",
"locales": ["String"]
},
"references": [
{
"type": Enum,
"id": "String"
}
],
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": Boolean,
"status": "Enum"
}
}
Request Body Parameters for ReferencedResourceVersionUpdate
Field | Description | Parameter Type | Required? |
---|---|---|---|
vendorId |
To get your vendor ID, go to https://developer.amazon.com/mycid.html. | String | Yes |
resource.id |
The ID of resource. | string | Yes |
resource.type |
"Catalog", "SlotType", or "InteractionModel" | String | Yes |
resource.locales |
The default is all available locales for the given skill. | String | No |
references |
Referenced resources that the "resource" field is dependent on. | resource array | No |
publishToLive |
Whether to publish the updated InteractionModel. | Boolean | Yes |
status |
Set to "ENABLED" or let it be null. | Enum | No |
Response
HTTP/1.1 200 OK
/v1/skills/api/custom/interactionModel/jobs/{jobId}
The jobId in the response has the following format: "amzn1.ask.jobId.$(UUID)". UUID is 16 octets (128 bits). Example: amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367
Exceptions
HTTP/1.1 400 Validation Error
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
Code | Message |
---|---|
INVALID_JOB_DEFINITION | The job definition isn't valid. |
INVALID_JOB_TYPE | The job type can't be changed after creation. |
INVALID_CATALOG_TYPE | The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL that can be automatically pulled from. |
DUPLICATE_JOB_DEFINITION | There is already the same type of job associated with the specified entityId. |
EXCEEDED_JOB_NUMBER_LIMIT | You've exceeded the limit, which is 20 jobs. |
INVALID_DEPENDENCY | The reference list contains a resource that isn't referenced by the job's main resource. |
TIME_WINDOW_UNAVAILABLE | The specified time window is full. Specify a different time window. |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Read Job Definition
Request
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}
The jobId in the request path is the identifier of the job definition. It is required.
Response
Response for CatalogAutoRefresh
{
"type": "CatalogAutoRefresh",
"resource": {
"id": "String",
"type": Enum
},
"trigger": {
"type": "Scheduled",
"hour": Integer,
"dayOfWeek": Integer
},
"status": Enum
}
Response for ReferenceVersionUpdate
{
"type": "ReferenceVersionUpdate",
"resource": {
"type": Enum,
"id": "String"
},
"references": [
{
"type": Enum,
"id": "String"
}
],
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": Boolean,
"status": Enum
}
Exceptions
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
List Jobs for Vendor ID
Request
GET /v1/skills/api/custom/interactionModel/jobs?vendorId=vendorId&maxCount=maxCount&nextToken=nextToken
Path Parameters
Parameter | Description | Required |
---|---|---|
maxCount | The maximum number of jobs to return per page. The default is 50. | No |
nextToken | The token to use to get the next page. | No |
Response
Response Body
{
"jobs": [{
"jobId": "String",
"jobType": Enum,
"status": Enum
}
],
"paginationContext": {
"nextToken": "String"
},
"_links": {
"next": {
"href": "String"
},
"self": {
"href": "String"
}
}
}
The status can be SUCCESS, FAILURE, IN_PROGRESS, SCHEDULED, or CANCELED.
Exceptions
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Delete Job
Request
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}
Response
HTTP/1.1 204 Success
The response to this operation doesn't have any content.
Exceptions
Code | Message |
---|---|
JOB_IN_USE | Other jobs depend on this job. Update or delete the dependent, then try again. |
ON_GOING_EXECUTION | The job is currently running. Try again later. |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
List Execution History
This operation lists the execution history of the specified job.
Request
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions?maxCount=maxCount&sortDirection=asc&nextToken=nextToken
Path Parameters
Parameter | Description | Required |
---|---|---|
jobId | The ID of the job definition. | Yes |
maxCount | The maximum number of results to return per page. The default is 50. | No |
nextToken | The token to use to get the next page. | No |
sortDirection | How you want the results to be sorted. The sorting is based on the executionTimestamp field. Specify "asc" for ascending or "desc" for descending. | No |
Response
HTTP/1.1 20O OK
Response Body
{
"executions": [{
"executionId": "String",
"executionTimestamp": "String", //ISO-8601
"errorCode": "String",
"status": Enum,
"errorDetails": {
"executionMetadata": [{
"jobId": "String",
"errorCode": "String",
"status": Enum
},
{
"jobId": "String",
"errorCode": "String",
"status": Enum
}]
}
}
],
"paginationContext": {
"nextToken": "String"
},
"_links": {
"next": {
"href": "String"
},
"self": {
"href": "String"
}
}
}
Response Body Parameters
Parameter | Description |
---|---|
executionTimestamp | The expected time to start the execution. It can be in the past. |
status | The current status of the update job. The following are the possible values: SUCCESS, FAILURE, IN_PROGRESS, SCHEDULED. |
errorCode | If the status is FAILURE, this error code explains what went wrong. |
executionMetadata | Details of the sub-executions. |
jobId | The ID of the execution job. |
Exceptions
HTTP/1.1 400
Code | Message | State of resources |
---|---|---|
ON_GOING_BUILD | Execution failed because the entity was being built and the retry period was exceeded. | Dev models not updated. |
INTERNAL_ERROR | The job failed due to a system error. | Live skill models not updated. Look for the latest version descriptions in development stages to see if development models were updated. |
INVALID_REQUEST | Update request was rejected because of a 400 error "_error_code_from_service". | Development model not updated. |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Cancel Next Execution
Cancel the next execution of the specified job.
Request
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions/{executionId}
Path Parameters
Parameter | Description |
---|---|
jobId | The ID of the job definition. |
executionId | This needs to be the ID of the latest execution, otherwise you get an exception. |
Response
HTTP/1.1 204 Accepted
Exceptions
HTTP/1.1 400
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
Code | Description |
---|---|
INVALID_JOB_TYPE | You can only cancel jobs of type CatalogAutoRefresh . |
INVALID_EXECUTION | This execution can't be canceled because the job is disabled or the execution has already been canceled or deleted. |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Enable or Disable Job
Request
PUT /v1/skills/api/custom/interactionModel/jobs/{jobId}/status
Request Body
{
"status": Enum
}
Path Parameters
Parameter | Description | Required |
---|---|---|
jobId | The ID of the job definition. | Yes |
status | ENABLED or DISABLED | Yes |
Response
HTTP/1.1 204 Accepted
Exceptions
HTTP/1.1 400
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
Code | Description |
---|---|
INVALID_JOB_STATUS | The job status is not defined. Specify only ENABLED or DISABLED. |
INVALID_EXECUTION | This execution can't be canceled because the job is disabled or the execution has already been canceled or deleted. |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Last updated: Jan 03, 2023