Job Management REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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	`POST /v1/skills/api/custom/interactionModel/jobs`
Cancel next scheduled job	`DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions/{runId}`
Delete job	`DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}`
Get job definition	`GET /v1/skills/api/custom/interactionModel/jobs/{jobId}`
Get job history	`GET /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions?sortDirection={sortDirection}&maxCount={maxCount}&nextToken={nextToken}`
List jobs	`GET /v1/skills/api/custom/interactionModel/jobs?vendorId={vendorId}&maxCount={maxCount}&nextToken={nextToken}`
Update job status	`PUT /v1/skills/api/custom/interactionModel/jobs/{jobId}/status`

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.

Note: You can specify whether you want the updates to happen every day or every week. However, you can't specify the exact time of day that the job runs.

Request

To create a job definition, you make a POST request to the interactionModel/jobs resource.

Request path and header example

Copied to clipboard.

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
`access token`	Header	LWA token.	String	Yes

Request body example for catalog refresh

Copied to clipboard.

{
    "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

Copied to clipboard.

{
    "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
`vendorId`	Identifies the vendor to which the skill belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`jobDefinition`	Defines the job.	Object	Yes
`jobDefinition.type`	Type of the job. Valid values: `CatalogAutoRefresh`, `ReferenceVersionUpdate`.	String	Yes
`jobDefinition.resource`	Resource that the job acts on, such as catalog or interaction model.	`Resource` object	Yes
`jobDefinition.references`	List of references on which the resource is dependent. Valid for `InteractionModel` resource type only.	Array of `Resource` objects	No
`jobDefinition.trigger`	Defines the job schedule and the condition that causes the job to run.	`Trigger` object	Yes
`jobDefinition.publishToLive`	Indicates whether to publish the development stage skill to live stage after the job completes. Valid and required for `ReferenceVersionUpdate` type only.	Boolean	No
`jobDefinition.status`	Indicates the state of the scheduled job. Valid values: `DISABLED`, `ENABLED`	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
`jobId`	Identifies the job that you created. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID.	String

HTTP status codes

Status	Description
`201 Created`	Job created successfully and the response body contains the job ID.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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.

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

Copied to clipboard.

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
`jobId`	Path	Identifies a job that you created. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID. Example: `amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367`.	String	Yes
`runId`	Path	Identifies the scheduled run. You can use Get job history to get the ID for a scheduled run.	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`	Successfully canceled the scheduled job run.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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.

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

Copied to clipboard.

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
`jobId`	Path	Identifies a job that you created. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID. Example: `amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367`.	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`	Successfully deleted the specified job.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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 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

Copied to clipboard.

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
`jobId`	Path	Identifies the job for which you want the run history. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID. Example: `amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367`.	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 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`	Type of the job. Valid values: `CatalogAutoRefresh`, `ReferenceVersionUpdate`.	String
`resource`	Resource that the job acts on.	`Resource` object
`references`	List of references on which the resource is dependent. Valid for `InteractionModel` resource type only.	Array of `Resource` objects
`trigger`	Defines the job schedule and the condition that causes the job to run.	`Trigger` object
`publishToLive`	Indicates whether to publish the development stage skill to live stage after the job completes. Valid and required for `ReferenceVersionUpdate` job definition type only.	Boolean
`status`	Indicates the state of the scheduled job. Valid values: `DISABLED`, `ENABLED`	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the details of the specified job.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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 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

Copied to clipboard.

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
`jobId`	Path	Identifies the job for which you want the run history. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID. Example: `amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367`.	String	Yes
`sortDirection`	Query	Set the sorting direction of the results as ascending or descending order. Valid values: `asc`, `desc`. Default: `desc`.	String	No
`maxCount`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	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 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
`executions`	List of runs for the specified job	Array of objects
`executions[].executionId`	Identifies the run.	String
`executions[].executionTimestamp`	Date and time of the run. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`executions[].status`	Current status of the run. Valid values: `SUCCESS`, `FAILURE`, `IN_PROGRESS`, `SCHEDULED`.	String
`executions[].errorCode`	(Optional) Included on failure. Describes the error.	String
`executions[].errorDetails`	(Optional) Included when the run depends on other runs.	Object
`executions[].errorDetails.executionMetadata`	(Optional) List of jobs upon which this job depends.	Array of objects
`executions[].errorDetails.executionMetadata[].jobId`	Identifies the dependent job. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID.	String
`executions[].errorDetails.executionMetadata[].status`	Current status of the run for the dependent job. Valid values: `SUCCESS`, `FAILURE`, `IN_PROGRESS`, `SCHEDULED`.	String
`executions[].errorDetails.executionMetadata[].errorCode`	(Optional) Included on failure. Describes the error of the dependent job.	String
`paginationContext`	(Optional) Wrapper for `nextToken`. Included when the response is paginated.	Object
`paginationContext.nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of runs and the status of each.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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.

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

Copied to clipboard.

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
`vendorId`	Query	Identifies the vendor to which the skill belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`maxCount`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	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 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
`jobs`	List of jobs defined for the specified vendor ID.	Array of objects
`jobs[].id`	Identifies the job. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID.	String
`jobs[].type`	Type of the job. Valid values: `CatalogAutoRefresh`, `ReferenceVersionUpdate`.	String
`jobs[].status`	Indicates the state of the job. Valid values: `DISABLED`, `ENABLED`	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of jobs defined for the vendor.
`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.

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

Copied to clipboard.

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
`jobId`	Path	Identifies the job for which you want to update the status. Formatted as: `amzn1.ask.jobId.{uuid}` where `uuid` is a 16 octet (128 bit) UUID. Example: `amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "status": "DISABLED"
}

Request body properties

Property	Description	Type	Required
`status`	Indicates the state of the scheduled job. Valid values: `DISABLED`, `ENABLED`	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
`HTTP 204 No Content`	Successfully updated the job status.
`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" }` Validation error codes: `DUPLICATE_JOB_DEFINITION` – There is already the same type of job associated with the specified resource ID. `EXCEEDED_JOB_NUMBER_LIMIT` – You've exceeded the limit on the number of jobs. Up to 20 jobs per vendor ID. `INVALID_CATALOG_TYPE` – The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL allows download. `INVALID_DEPENDENCY` – The `reference` list contains a resource that isn't referenced by the job `resource`. `INVALID_EXECUTION` – You can't cancel the scheduled run because the job is disabled or you already canceled or deleted the scheduled run. `INVALID_JOB_DEFINITION` – The job definition isn't valid. `INVALID_JOB_STATUS` – The job status isn't valid. Specify `ENABLED` or `DISABLED`. `INVALID_JOB_TYPE` – You can only cancel jobs of type `CatalogAutoRefresh`. `INVALID_REQUEST` – The development model wasn't updated. `INTERNAL_ERROR` – The job failed due to system error and the live skill interaction model wasn't updated. Check to see if the development version was updated. `JOB_IN_USE` – Other jobs depend on this job. Update or delete the dependent job, and then try again. `ON_GOING_BUILD` – The job is running at this time and the interaction model wasn't updated. Try again later. `TIME_WINDOW_UNAVAILABLE` – The specified time window is full. Specify a different time window.
`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 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.
`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 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
`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)

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`	Type of the resource. Valid values: `Catalog`, `InteractionModel`.	String	Yes
`id`	Identifies the resource. Based on the `resource.type`, set to catalog ID or skill ID.	String	Yes
`locales`	List of locales to create the job for. Valid for `InteractionModel` resource type only. Default: All locales.	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`	Type of the trigger. Valid values: `Scheduled`, `ReferencedResourceJobsComplete`.	String	Yes
`hour`	Hour of the day that the job starts. Include for trigger type of `Scheduled`. Valid values: 0, 4, 8, 12, 16, 20.	Integer	No
`dayOfWeek`	Day of the week that the job starts. Indicates that you want to schedule the job weekly. If you don't specify `trigger.dayOfWeek`, the job runs daily by default. Include for trigger type of `Scheduled`. Valid values: 0 – 6.	Integer	No

Last updated: May 11, 2023