Job Management REST API Reference
Use the Job Management REST API to create and manage jobs that automatically update reference-based catalogs or interaction models. For details about catalogs, see Interaction Model Catalog Management REST API Reference.
When you create a job, you define the schedule for the job to run, either daily or weekly. With the API, you can get the details of the job, status of completed job runs, and cancel the next scheduled job.
API endpoint
The endpoint of the Job Management 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 Job Management API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
| |
|
Create job definition
Define and schedule a new job. You can define one of the following types of jobs:
CatalogAutoRefresh
– Creates a job to update a catalog.ReferencedResourceVersionUpdate
– Creates a job to update voice interaction models.
You can create up to 20 jobs.
Request
To create a job definition, you make a POST
request to the interactionModel/jobs
resource.
Request path and header example
POST /v1/skills/api/custom/interactionModel/jobs
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example for catalog refresh
{
"vendorId": "your.vendor.id.1",
"jobDefinition": {
"type": "CatalogAutoRefresh",
"resource": {
"id": "catalog.id.1",
"type": "Catalog"
},
"trigger": {
"type": "Scheduled",
"hour": 20,
"dayOfWeek": 2
},
"status": "ENABLED"
}
}
Request body example for resource update
{
"vendorId": "your.vendor.id.1",
"jobDefinition": {
"type": "ReferenceVersionUpdate",
"resource": {
"type": "InteractionModel",
"id": "amzn1.ask.skill.1",
"locales": ["en-US"]
},
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": true
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Identifies the vendor to which the skill belongs. |
String |
Yes |
|
Defines the job. |
Object |
Yes |
|
Type of the job. |
String |
Yes |
|
Resource that the job acts on, such as catalog or interaction model. |
|
Yes |
|
List of references on which the resource is dependent. |
Array of |
No |
|
Defines the job schedule and the condition that causes the job to run. |
|
Yes |
|
Indicates whether to publish the development stage skill to live stage after the job completes. |
Boolean |
No |
|
Indicates the state of the scheduled job. |
String |
No |
Response
A successful response returns HTTP 201 Created
, along with the ID of the new job.
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
{
"jobId": "amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the job that you created. |
String |
HTTP status codes
Status | Description |
---|---|
|
Job created successfully and the response body contains the job ID. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Cancel next scheduled job
Cancel the next scheduled run of the specified job.
Request
To cancel a scheduled run, you make a DELETE
request to the interactionModel/jobs
resource.
Request path and header example
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions/{runId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies a job that you created. |
String |
Yes |
|
Path |
Identifies the scheduled run. |
String |
Yes |
|
Header |
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 |
---|---|
|
Successfully canceled the scheduled job run. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete job
Deletes a specified job by job ID.
Request
To remove a job, you make a DELETE
request to the interactionModel/jobs
resource.
Request path and header example
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies a job that you created. |
String |
Yes |
|
Header |
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 |
---|---|
|
Successfully deleted the specified job. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get job definition
Get the definition for the specified job.
Request
To get the specified job, you make a GET
request to the interactionModel/jobs
resource.
Request path and header example
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}
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 |
---|---|---|---|---|
|
Path |
Identifies the job for which you want the run history. |
String |
Yes |
|
Header |
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 details of the specified job.
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 for catalog refresh job
{
"type": "CatalogAutoRefresh",
"resource": {
"id": "catalog.id.1",
"type": "Catalog"
},
"trigger": {
"type": "Scheduled",
"hour": 20,
"dayOfWeek": 2
},
"status": "ENABLED"
}
Response body example for resource update job
{
"type": "ReferenceVersionUpdate",
"resource": {
"type": "InteractionModel",
"id": "amzn1.ask.skill.1",
"locales": ["en-US"]
},
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": true,
"status": "DISABLED"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Type of the job. |
String |
|
Resource that the job acts on. |
|
|
List of references on which the resource is dependent. Valid for |
Array of |
|
Defines the job schedule and the condition that causes the job to run. |
|
|
Indicates whether to publish the development stage skill to live stage after the job completes. Valid and required for |
Boolean |
|
Indicates the state of the scheduled job.
Valid values: |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the details of the specified job. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get job history
Get the history of scheduled, ongoing, and completed runs of the specified job.
Request
To get the run history, you make a GET
request to the interactionModel/jobs
resource.
Request path and header example
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions?sortDirection={sortDirection}&maxCount={maxCount}&nextToken={nextToken}
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 |
---|---|---|---|---|
|
Path |
Identifies the job for which you want the run history. |
String |
Yes |
|
Query |
Set the sorting direction of the results as ascending or descending order. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
Header |
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 runs.
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
{
"executions": [{
"executionId": "run.id.1",
"executionTimestamp": "2019-01-06T05:26:02.430Z",
"status": "SCHEDULED"
}],
"paginationContext": {
"nextToken": "someToken.1"
},
"_links": {
"next": {
"href": "/v1/skills/api/custom/interactionModel/jobs/amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367/executions?nextToken=someToken.1&maxCount=10"
},
"self": {
"href": "/v1/skills/api/custom/interactionModel/jobs/amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367/executions"
}
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of runs for the specified job |
Array of objects |
|
Identifies the run. |
String |
|
Date and time of the run. |
String |
|
Current status of the run. |
String |
|
(Optional) Included on failure. Describes the error. |
String |
|
(Optional) Included when the run depends on other runs. |
Object |
|
(Optional) List of jobs upon which this job depends. |
Array of objects |
|
Identifies the dependent job. |
String |
|
Current status of the run for the dependent job. |
String |
|
(Optional) Included on failure. Describes the error of the dependent job. |
String |
|
(Optional) Wrapper for |
Object |
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
String |
|
Links for item navigation. |
_links object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of runs and the status of each. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List jobs
List the jobs by vendor ID.
Request
To list the jobs, you make a GET
request to the interactionModel/jobs
resource.
Request path and header example
GET /v1/skills/api/custom/interactionModel/jobs?vendorId={vendorId}&maxCount={maxCount}&nextToken={nextToken}
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 |
---|---|---|---|---|
|
Query |
Identifies the vendor to which the skill belongs. |
String |
Yes |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
Header |
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 jobs.
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
{
"jobs": [{
"id": "amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367",
"type": "CatalogAutoRefresh",
"status": "ENABLED"
}],
"paginationContext": {
"nextToken": "someToken.1"
},
"_links": {
"next": {
"href": "/v1/skills/api/custom/interactionModel/jobs/your.vendor.id.1/executions?nextToken=someToken.1&maxCount=10"
},
"self": {
"href": "/v1/skills/api/custom/interactionModel/jobs/your.vendor.id.1"
}
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of jobs defined for the specified vendor ID. |
Array of objects |
|
Identifies the job. |
String |
|
Type of the job. |
String |
|
Indicates the state of the job.
Valid values: |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of jobs defined for the vendor. |
|
Indicates that one or more properties in the request body are invalid.
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
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. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update job status
Update the status of the specified job to enabled or disabled.
Request
To update the job status, you make a PUT
request to the interactionModel/jobs
resource.
Request path and header example
PUT /v1/skills/api/custom/interactionModel/jobs/{jobId}/status
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the job for which you want to update the status. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"status": "DISABLED"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Indicates the state of the scheduled job. |
String |
No |
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 |
---|---|
|
Successfully updated the job status. |
|
Indicates that one or more properties in the request body are invalid.
Validation error codes:
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill exceeded the permitted rate limit or specified number of requests per unit of time. The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Job Management API defines the following object definitions.
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 |
---|---|
|
Arabic (SA) |
|
German (DE) |
|
English (AU) |
|
English (CA) |
|
English (UK) |
|
English (IN) |
|
English (US) |
|
Spanish (ES) |
|
Spanish (MX) |
|
Spanish (US) |
|
French (CA) |
|
French (FR) |
|
Hindi (IN) |
|
Italian (IT) |
|
Japanese (JP) |
|
Portuguese (BR) |
Resource object
The Resource
object represents the information that the job acts on, such as a catalog or interaction model.
Property | Description | Type | Required |
---|---|---|---|
|
Type of the resource. |
String |
Yes |
|
Identifies the resource. |
String |
Yes |
|
List of locales to create the job for. |
Array of string |
No |
Trigger
The Trigger
object defines the job schedule and the condition that causes the job to run.
Property | Description | Type | Required |
---|---|---|---|
|
Type of the trigger. |
String |
Yes |
|
Hour of the day that the job starts. Include for trigger type of |
Integer |
No |
|
Day of the week that the job starts. Indicates that you want to schedule the job weekly. If you don't specify |
Integer |
No |
Related topics
Last updated: May 11, 2023