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

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.

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