Manage Update Jobs

You can use the APIs described in this document to create and manage jobs that automatically update reference-based catalogs. For information about reference-based catalogs, see Reference-Based Catalog Management.

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

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": "Schedule",
          "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 "Schedule" 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": "Schedule",
        "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